Document Transformation Services Administration Guide

Transcription

1 Document Transformation Services Administration Guide Version 5.3 March 2005

2 Copyright EMC Corporation

3 Table of Contents Preface... 7 Chapter 1 Document Transformation Services Overview... 9 What is Content Transformation Services?... 9 What is Document Transformation Services? Document Transformation Services Environment Document Transformation Services Components Document Transformation Server Documentum Foundation Classes (DFC) Plug-ins in Document Transformation Services Content Transformation Services Scalability How Document Transformation Services Works How Document Transformation Services Creates PDF Renditions How Document Transformation Services Creates HTML Renditions Features of Document Transformation Services Document Transformation Services Capabilities Supported Transformations by Source and Target Formats Required Applications for Supported Source Formats Chapter 2 Con guring Document Transformation Services Configuring Document Transformation Services through Documentum Administrator Starting and Stopping the CTS Admin Agent Changing Repositories Serviced by Document Transformation Services Changing the Repository Login User Name Changing the Queue Interval Changing the Document Transformation Services System Operator Defining File Formats and DOS Extensions Customizing Printing and Rendition Options Specifying an Alternate Printer Saving PostScript Renditions Choosing Whether to Save PDT Files Chapter 3 Administering Document Transformation Services Administering Document Transformation Services through Documentum Administrator Starting and Stopping the CTS Admin Agent Starting and Stopping Document Transformation Services Transferring Document Attributes Document Transformation Services Administration Guide 3

4 Table of Contents Transferring Document Attributes to PDF and Embedding Metadata Opening New repository Sessions with Ticketed Logins Viewing the Attributes in the PDF Rendition Altering Timing and Operational Parameters Controlling How Quickly Programs Time Out Controlling the Document Transformation Services Log Level Chapter 4 Transformation Pro les Understanding Command-line Files Modifying a System Profile Configuring Legacy Custom OLE Plug-ins Chapter 5 Troubleshooting Error events and log files The Transformation Request Fails An Error Related to Profiles Occurs Document Transformation Server Cannot Add a Rendition to a Particular Format Document Transformation Server Cannot Log in to the repository Document Transformation Services Administration Guide

5 Table of Contents List of Figures Figure 1 1. Typical Document Transformation Services Installation Figure 1 2. Processing a Request for a PDF Rendition Figure 1 3. Processing a Request for an HTML rendition Document Transformation Services Administration Guide 5

6 Table of Contents List of Tables Table 1 1. Document Transformation Services Features Table 1 2. Document Transformation Services Supported Capabilities Table 1 3. Supported Transformations with Document Transformation Services by Source and Target Formats Table 1 4. Required Applications for Supported Source Formats Table 2 1. File Format Attributes Table 3 1. Attribute mapping arguments Document Transformation Services Administration Guide

7 Preface This guide provides step-by-step procedures for configuring and administering Documentum Document Transformation Services. This manual also includes information about writing Plug-ins to extend the functionality of Document Transformation Services. You can find additional information about Document Transformation Services in the following documents: Document Transformation Services Installation Guide Document Transformation Services Release Notes See the appropriate Documentum product documentation for information on related Documentum products. Intended Audience The primary audience for this guide is the system administrator who maintains this software. The secondary audience is the system integrator who wishes to extend Document Transformation Services functionality. Familiarity with Microsoft Windows and the Documentum system is essential. Revision History The following changes have been made to this document. Revision Date March 2005 Description Initial Publication for 5.3 Product Release Document Transformation Services Administration Guide 7

8 Preface 8 Document Transformation Services Administration Guide

9 Chapter 1 Document Transformation Services Overview This chapter contains a brief overview of Document Transformation Services and outlines a typical Document Transformation Services installation. It gives a basic description of the basic Documentum environment and relates the Document Transformation Services components within the installation. This chapter contains the following sections: What is Content Transformation Services?, page 9 is a brief overview of Content Transformation Services and the set of products that the term is commonly used to describe. What is Document Transformation Services?, page 10 is an introduction to Document Transformation Services with a general description of its major components, a brief explanation of how Document Transformation Services works with your Documentum installation and describes how Document Transformation Services integrates with other Documentum products. It also describes the scalability of Content Transformation Services products. Supported Transformations by Source and Target Formats, page 17 includes tables of supported transformations by source and target formats, as well as the required applications for the source formats. What is Content Transformation Services? Content Transformation Services is a name used for a set of Documentum server products that perform transformations and analysis on repository content. Content Transformation Services (CTS) includes the main products Document Transformation Services (DTS), Advanced Document Transformation Services (ADTS), and Media Transformation Services (MTS). Additional components for those products may be available, depending on the product. For example, Media Transformation Services may have additional transformation services installed, such as Audio/Video Transformation Services (AVTS), Medical Imaging Transformation Services (MITS), and Optical Character Recognition Transformation Services (OCRTS). These components supplement Document Transformation Services Administration Guide 9

10 Document Transformation Services Overview the features already provided by the base product, according to your organization s requirements. What is Document Transformation Services? Document Transformation Services is server software that generates copies of documents in Adobe s Portable Document Format (PDF), PDF Text, PostScript, and HTML. You can use Documentum client applications to request such a copy (called a rendition) of a document stored in a Documentum repository. Some Documentum client applications may not provide both PDF and HTML renditions; consult the documentation for the client you are using. Note: Document Transformation Services cannot process documents that are locked (that is, checked out from the repository). Document Transformation Services Environment Figure 1 1, page 10 shows a typical Document Transformation Services installation on the Documentum platform. Figure 1-1. Typical Document Transformation Services Installation 10 Document Transformation Services Administration Guide

11 Document Transformation Services Overview Document Transformation Services Components Document Transformation Services is an added component to your basic Documentum installation that includes Content Server and defined repositories with file stores. The following sections detail the main components that make up a Document Transformation Services installation. Document Transformation Server Document Transformation Services is integrated with Documentum Content Server to process, store, and manage files within the Documentum schema. When users import files or request file transformations, the Content Server stores those register and request objects in a queue. The Document Transformation Server will poll that queue intermittently, looking for register and transformation request objects. The file is then passed to the appropriate Transformation Service Plug-in for processing. When the processing is complete, the Document Transformation Server updates the original objects with new renditions or creates the new objects, as requested. The objects are saved to the repository and the requests are removed from the queue. The objects are then ready for use. Documentum Foundation Classes (DFC) The Documentum Foundation Classes (DFC) are a set of Java classes that provide access to Content Server functionality. Web-based applications, such as Digital Asset Manager and WebPublisher, make calls directly to the DFC or indirectly through the Web Development Kit (WDK). Documentum Foundation Classes (DFC) must be installed on the Document Transformation Services host. If you are installing Document Transformation Services on a host that may already have the DFC, Document Transformation Services may be able to use the existing DFC, provided it is the correct version. A verification of your existing DFC, if there are any, is performed by the Document Transformation Services installer. If the DFC is detected, it will be replaced by the version included with the installer. Refer to the relevant version of the Documentum System Migration Guide available on the Download Center at for more information on migration issues. This means that any applications that were dependant upon the older version of the DFC will have to be upgraded as well. For more information on the DFC and its affect on other applications, please see your specific Documentum application documentation. Document Transformation Services Administration Guide 11

12 Document Transformation Services Overview If you have a version newer than the DFC included with the installer, it will be left untouched. Plug-ins in Document Transformation Services The Document Transformation Server Plug-ins enable users to transform a variety of files from one format to another (for example, from DOC to PDF or HTML). During an installation of Document Transformation Services, all standard Plug-ins are installed. The standard Document Transformation Server Plug-ins are as follows: POWERPOINT Transforms Microsoft PowerPoint files to PostScript. WORD Transforms Microsoft Word files to PostScript. EXCEL Transforms Microsoft Excel files to PostScript. WORDPERFECT Transforms Corel WordPerfect files to PostScript. ACROBAT Creates PDFText. DISTILLER Transforms PostScript to PDF. Plug-ins are extensible. You can configure Plug-in types and formats, and you can add new Plug-ins to the system to support new file formats as required. For information about creating and adding new Plug-ins, please see the Document Transformation Services Administration Guide, or contact your Documentum account or support representative. Content Transformation Services Scalability Content Transformation Services (CTS) products allow for a high level of scalability. All CTS products run under the same Windows Service on the CTS host. This means that stopping or starting that CTS service stops or starts all the CTS products on that host. For example, if your CTS host contains Document Transformation Services and Media Transformation Services, stopping the CTS Windows Service stops both of those products. However, each CTS product can be configured for multiple repositories. For example, if you have one installation of Document Transformation Services on a host, that installation can be configured against multiple repositories. CTS scalability also means that you can have several instances of Content Transformation Services products on different hosts configured for the same repository. This means that your installation can take either of two forms: one with identical Plug-in capabilities, and one with different Plug-in capabilities. 12 Document Transformation Services Administration Guide

13 Document Transformation Services Overview For example, the ability for each instance of Advanced Document Transformation Server to handle different Plug-ins means that you can have each instance dedicated to a specific type of transformation. For example, you might have a dedicated Advanced Document Transformation Server for transformation to PDF and a dedicated Advanced Document Transformation Server for transformation to HTML, each with different Plug-ins, but pointing to the same repository. The other benefit of having identical Content Transformation Services installations, is that a hardware failure in one instance will not stop all installations from processing queue items. In cases where each instance of a Content Transformation Services has different Plug-in capabilities, each server accepts only those items from the processing queue that it is capable of handling. For this to happen, it means that Content Transformation Services has format awareness. Format awareness is the ability for a Content Transformation Services product to recognize which file formats it is capable of processing. Items that cannot be processed successfully will be removed from the queue automatically. For example, if several transformation requests are made for JPEG files, but there is no support for JPEGs, the system will remove those items from the queue. A check for unprocessed items is performed periodically. How Document Transformation Services Works The following sections how Document Transformation Services works to create PDF and HTML renditions. How Document Transformation Services Creates PDF Renditions The following steps show how Document Transformation Services produces PDF renditions in response to client requests (see Figure 1 2, page 14): 1. The client application sends the rendition request to Documentum Content Server. Note: Because Document Transformation Services modifies the document object, it cannot process locked (checked out) documents. 2. Content Server stores the request in a special queue called dm_queue. 3. Document Transformation Server polls dm_queue at predefined intervals, and retrieves any pending requests. 4. When Document Transformation Services finds a PDF rendition request in the queue, it checks the format of the document and generates a PDF, PostScript, or PDFText rendition based on what the default profiles specify (through legacy client invoking). Document Transformation Services Administration Guide 13

14 Document Transformation Services Overview If the document is a PDF file Document Transformation Services calls the pdftext.api plugin to Acrobat to generate a PDF Text file. When a PDF rendition is requested for some source file formats, Document Transformation Services can optionally generate and store a PostScript representation of the input file. 5. Content Server adds the PDF and PDF Text renditions to the object in the repository. An object represents a parent file, with all of its associated graphics, text, and renditions, in the repository. Once a rendition has been added to the object, users can view the rendition from the client application. Figure 1-2. Processing a Request for a PDF Rendition How Document Transformation Services Creates HTML Renditions The following steps show how a Document Transformation Services host produces HTML renditions in response to client requests (see Figure 1 3, page 15). 1. The client application sends the rendition request to the Content Server. Note: Document Transformation Services cannot process documents that are locked (checked out from the repository). 2. Content Server stores the request in a special queue called dm_queue. 3. Document Transformation Server polls dm_queue at predefined intervals, and retrieves any pending requests. 4. When Document Transformation Services finds an HTML rendition request in the queue, it checks the format of the document. Document Transformation Services 14 Document Transformation Services Administration Guide

15 Document Transformation Services Overview invokes the corresponding application to open the file and then saves an HTML version. If the result is a single HTML file, Document Transformation Services sends this file to the Content Server. If the result consists of multiple files (for example, HTML, graphics, and XML files), Document Transformation Services creates a Zip file containing these files, and sends the Zip file to Content Server. The Zip file includes any folders the application creates to contain these files. 5. Content Server adds the HTML or Zip file to the repository as a rendition of the document object. An object represents a parent file, with all of its associated graphics, text, and renditions, in the repository. Once a rendition has been added to the object, users can view the rendition from the client application. Figure 1-3. Processing a Request for an HTML rendition Features of Document Transformation Services The following are the features that Document Transformation Services offers. Additional features and capabilities are available with Advanced Document Transformation Services. For more information, see the Advanced Document Transformation Services product documentation or contact your account representative. Document Transformation Services Administration Guide 15

16 Document Transformation Services Overview Table 1-1. Document Transformation Services Features Feature Runs as Windows Service and intelligently handles exceptions raised by native applications Transforms common document formats into PDF, PDF Text, PostScript, and HTML Creates new renditions Embeds Documentum attributes into file properties Integrates with entire Documentum product suite and is backwards compatible Available with Document Transformation Services Yes Yes Yes Yes Yes Comments PDFText and PostScript transformations are disabled by default. Compatible with Content Server and later. Document Transformation Services Capabilities The following table details out of the box capabilities of Document Transformation Services. Table 1-2. Document Transformation Services Supported Capabilities Input Format Create Thumbnail Create Storyboard Create Low-Res Rendition Extract XMP to Object Embed XMP to Object DOC DOT XLS POT PPT PPS WPD TXT 16 Document Transformation Services Administration Guide

17 Document Transformation Services Overview RTF PS PDF HTML ZIP_HTML x Supported Transformations by Source and Target Formats With the required supporting applications installed, Document Transformation Services can perform the following transformations. Table 1-3. Supported Transformations with Document Transformation Services by Source and Target Formats Source Format Microsoft Word (DOC, DOT) 97, 2000, 2003, XP Microsoft Excel (XLS) 97, 2000, 2003, XP Microsoft PowerPoint (POT, PPT) 97, 2000, 2003, XP Corel WordPerfect (WPD) 7, 8, 10, 11 TXT and RTF PostScript (PS) Level 2, 3 Portable Document Format (PDF) 1.3, 1.4 HTML ZIP_HTML Target Formats PDF, PDF Text, PS, HTML PDF, PDF Text, PS, HTML PDF, PDF Text, PS, HTML PDF, PDF Text, PS, HTML PDF, PDF Text, PS, HTML PDF, PDFText PDF, PDFText PDF, PDFText PDF, PDFText Required Applications for Supported Source Formats The supported transformations are dependant upon the installation of a variety of applications on the Document Transformation Services, as detailed in Table 1 4, page 18. Document Transformation Services Administration Guide 17

18 Document Transformation Services Overview Table 1-4. Required Applications for Supported Source Formats Source Format Word Excel PowerPoint Required Rendering Applications Word 2000/2003/XP* Excel 2000/2003/XP* Power Point 2000/2003/XP* WordPerfect Word Perfect 10/11* PDF Acrobat 5.0.5/6.0 PostScript Acrobat 5.0.5/6.0 Text, RTF, HTML, ZIP_HTML Word 2000/2003/XP * The Document Transformation Server should have the "latest" version of the rendering applications that the clients will be using. For example, if clients will be transforming Word 2003 files, the Document Transformation Server should have Word 2003 installed. Versions of Word older than 2003 may not be able to handle documents created with Word Document Transformation Services Administration Guide

19 Chapter 2 Con guring Document Transformation Services This chapter contains instructions for configuring Document Transformation Services on Windows. Con guring Document Transformation Services through Documentum Administrator Many configuration tasks for Document Transformation Services can now be done through the CTS Administration component of Documentum Administrator. You must have access to Documentum Administrator and the repositories to which Document Transformation Services is configured against. The Content Transformation Services Administration component appears in Documentum Administrator if at least one instance is installed and configured on a repository to which it is connected. This check is done through executing the DQL/DFC call to find the presence of at least one cts_instance_info object in the repository. The following Document Transformation Services administration and configuration tasks can be performed through Documentum Administrator client, in the CTS Administration Node: Changing the User for repository login. Changing the system operator user. The System Operator is the name of the user that receives messages from an instance of Document Transformation Services. If Document Transformation Server fails to process a particular item, it queues an event (dm_mediaserver_error) to the Inbox of the repository user who is defined as the Document Transformation Server System Operator (sysopuser). The event appears as an error message in the sysopuser s Inbox. Changing the polling level. The polling interval is the amount of time in seconds that the instance will wait between polls. Document Transformation Services Administration Guide 19

20 Con guring Document Transformation Services When document processing is requested (transformation), Content Server creates queue items and appends them to the dm_mediaserver queue or dm_autorender_win31 queue depending on the type of request. Document Transformation Server uses a queue polling mechanism to look for items in the queue that it has to process. When Document Transformation Server finds items in any of these queues, it proceeds with processing Changing the logging level. The logging level value controls how much information will be recorded in the CTS log files, which Document Transformation Services uses. Changing the system notification setting. Changing the maximum number of queue items. This value controls how many items the Document Transformation Services instance adds for processing each time it polls the queue. Changing the queue item expiry. This value controls the amount of time an item will be sitting on a queue before being deleted from the queue. For more information on the configuration tasks noted above, see the Documentum Administrator User Guide. Starting and Stopping the CTS Admin Agent In order to use the Content Transformation Services Administration component in Documentum Administration, it is necessary to have the CTS Admin Agent running on the CTS host machine. To start the CTS Admin Agent: 1. Log in to the Document Transformation Services host. 2. Go to the Windows Services utility located at Start Settings Control Panel Administrative Tools Services. 3. Highlight Documentum CTS Admin. Agent and click Start. - OR - 1. Navigate to C:\Program Files\Documentum\CTS\AdminAgent\bin. 2. Launch the startup.bat batch file. To stop the CTS Admin Agent: 1. Log in to the Document Transformation Services host. 2. Go to the Windows Services utility located at Start Settings Control Panel Administrative Tools Services. 3. Highlight Documentum CTS Admin. Agent and click Stop. 20 Document Transformation Services Administration Guide

21 Con guring Document Transformation Services - OR - 1. Navigate to C:\Program Files\Documentum\CTS\AdminAgent\bin. 2. Run the shutdown.bat batch file. Changing Repositories Serviced by Document Transformation Services During installation, the Document Transformation Server is configured to communicate with single or multiple repositories. You can change add or remove a repository by running the Document Transformation Services Configurator (Accessible through Windows menu Start Programs Documentum DTS Instance Add or Remove). For information on the Configurator and how to run it, see the Document Transformation Services Installation Guide. Note: You must have SuperUser privileges for a repository in order to add it to Document Transformation Services. Changing the Repository Login User Name Document Transformation Services logs in to the repository as a superuser. To change the repository login user information, you must edit the SessionService.xml file. Note: This task can also be performed through the Content Transformation Services Administration component in Documentum Administrator. See Configuring Document Transformation Services through Documentum Administrator, page 19. To change the repository login user information: 1. Log in to the Document Transformation Services host as an administrator. 2. Stop the Content Transformation Services service. 3. Open the Content Transformation Services services directory, located in \%CTS_HOME%\CTS\config\ (default location for CTS_HOME is C:\Program Files\Documentum\CTS) 4. Open the SessionService.xml file in any text editor. 5. Scroll down to the line that begins with the LoginContext of a particular repository. 6. Within that LoginContext, Scroll down to the line that begins <MediaServer AttributeName="userName" AttributeValue=<user_name>/> Document Transformation Services Administration Guide 21

22 Con guring Document Transformation Services 7. Change the value of the AttributeValue attribute of the AttributeName element username to a repository user who has superuser privileges. 8. Scroll down to the line that begins <MediaServer AttributeName="passwordFile" AttributeValue= <path_to_appropriate_mspassword.txt>/> 9. Change the value of the AttributeValue attribute of the AttributeName element passwordfile to the user s repository password file, using the full file path. 10. Save and close the SessionService.xml file. 11. Restart the Content Transformation Services service. Changing the Queue Interval When document processing is requested (transformation), Content Server creates queue items and appends them to the dm_mediaserver queue or dm_autorender_win31 queue depending on the type of request. Document Transformation Services uses a queue polling mechanism to look for items in the queue that it has to process. When Document Transformation Services finds items in any of these queues, it proceeds with processing. By default, Document Transformation Services polls the queues at 10-second intervals, but you can set the interval to another value by editing the file MediaServerService.xml. Note: This task can also be performed through the Content Transformation Services Administration component in Documentum Administrator. See Configuring Document Transformation Services through Documentum Administrator, page 19. To change the queue interval: 1. Log in to the Document Transformation Services host as an administrator. 2. Stop the Content Transformation Services service. 3. Open the Document Transformation Services services directory, located in \%CTS_HOME%\CTS\config\ (default location for CTS_HOME is C:\Program Files\Documentum\CTS) 4. Open the MediaServerService.xml file in any text editor. 5. Scroll down to the line that begins with QueueProcessorContext of a particular repository. Note: There will be two QueueProcessorContexts, so make the following changes in both QueueProcessorContexts. 6. Within the QueueProcessorContext, scroll down to the line that begins <MediaServer AttributeName="queueInterval" AttributeValue="10"/> 22 Document Transformation Services Administration Guide

23 Con guring Document Transformation Services 7. Change the value of the AttributeValue attribute of the AttributeName element queueinterval to a new numeric interval value, in seconds. 8. Save and close the MediaServerService.xml file. 9. Restart the Content Transformation Services service. Changing the Document Transformation Services System Operator If Document Transformation Services fails to process a particular item, it queues an event (dm_mediaserver_error) to the Inbox of the repository user who is defined as the Document Transformation Services System Operator (sysopuser). The event appears as an error message in the sysopuser s Inbox. You can identify the Document Transformation Services System Operator by editing the file MediaServerService.xml. Note: This task can also be performed through the Content Transformation Services Administration component in Documentum Administrator. See Configuring Document Transformation Services through Documentum Administrator, page 19. To identify the Document Transformation Services system operator: 1. Log in to the Document Transformation Services host as an administrator. 2. Stop the Content Transformation Services service. 3. Open the Document Transformation Services services directory, located in \%CTS_HOME%\CTS\config\ (default location for CTS_HOME is C:\Program Files\Documentum\CTS) 4. Open the MediaServerService.xml file in any text editor. 5. Scroll down to the line that begins with QueueProcessorContext of a particular repository. Note: There will be two QueueProcessorContexts, so make the following changes in both QueueProcessorContexts. 6. Within the QueueProcessorContext, scroll down to the line that begins <MediaServer AttributeName="sysOpUserName" AttributeValue=<user_name>"/> 7. Change the value of the AttributeValue attribute of the AttributeName element sysopusername to the name of the repository user who should receive Document Transformation Services error messages. 8. Save and close the MediaServerService.xml file. Document Transformation Services Administration Guide 23

24 Con guring Document Transformation Services 9. Restart the Content Transformation Services service. De ning File Formats and DOS Extensions You must define file formats and DOS file extension pairs in the repository for all source document types that you want Document Transformation Services to recognize. To add a le format using Documentum Administrator: 1. Start Documentum Administrator and connect to the repository to which you want to add the new file format. 2. Under repository Management, click Formats. The Formats page appears. 3. Click NEW. The Create New Format Object page appears. 4. Enter the general attributes for the format: Table 2-1. File Format Attributes Field Name Description Default File Extension Com Class ID Mime Type Windows Application Is Hidden Value Name of the format object Description of the format Examples of valid file extensions are: ppt for PowerPoint xls for Excel doc for Word wpd or wpd5 for WordPerfect Com registry ID for the format The Multimedia Internet Mail Extension (MIME) designation for the content type Name of an application to launch when users select a document in the format represented by the format object Used by client applications 24 Document Transformation Services Administration Guide

25 Con guring Document Transformation Services Macintosh Creator Macintosh Type Information used internally for managing Macintosh resource files Information used internally for managing Macintosh resource files The Macintosh Type and Creator values are necessary for users to access files in this format from Macintosh clients. 5. If the format is indexable, define the indexing options. a. Check the Can Be Indexed checkbox. b. To index with a filter, click Index with Filter and select the filter from the drop-down list. By default, all formats installed with the Content Server use the universal filter. c. To index with a rendition, select Index with Rendition and select the rendition format from the drop-down list. This is the format in which the document will be indexed if its original format is not used for indexing. If you are indexing the PDFText rendition of documents in this format, set this to pdftext. 6. Click Create. A confirmation page appears. You can create a new template for this format by clicking Create New Template for this Format. Customizing Printing and Rendition Options The PostScript Printer Driver is responsible for generating the PostScript outputs. In the background mode the Adobe Postscript Printer Driver uses this postscript file to generate the PDF Renditions. You can modify the profiles and command line files to: specify an alternate printer. save the PostScript rendition of a document (created during the Render as PDF operation). choose whether or not to save the PDT file. Specifying an Alternate Printer By default, Document Transformation Services uses the Adobe Acrobat Distiller (for Acrobat 5) or the Adobe PDF Printer driver (for Acrobat 6) to generate the PDF and PostScript outputs. However, if you must use a version of Adobe products different Document Transformation Services Administration Guide 25

26 Con guring Document Transformation Services from that detailed in the Document Transformation Services installation instructions, or if you must give your printers a specific name, you can change the default Document Transformation Services printer specification in the corresponding command line files. To do this, change the following tag from all the command line files so that it matches the name of your default printer and the printer output name, if it is configured to some other value. <PROP name="pdf Printer Name" type="string" token="doc_token_pdfdriver"> Adobe PDFPROP name="pdf Printer Name" type="string" token="doc_token_pdfdriver"> Adobe PDF</PROP> <PROP name="pdf Printer Output" type="string" token="doc_token_pdfoutput">c:\ctszone </PROP> If the transformation is performed through Transformation Profiles, this can be added in the drop down value list of the corresponding profile in the Documentum client. Note: Use the Windows printer name as it appears in Start Settings Printers on the Document Transformation Services host. Saving PostScript Renditions You may wish to store the PostScript rendition of a document as well as the PDF and PDT renditions. The PostScript rendition of a document may be useful if you intend to automate printing or faxing of the document. By default, this capability is not enabled. If you wish to enable saving of PostScript renditions, navigate to the repository folder System\Media Server\System Profiles and open the file legacy_to_pdf. Uncomment the following section: <PROP name="store Postscript Rendition" type="string" token="doc_token_storepsrendition">trueprop name="store Postscript Rendition" type="string" token="doc_token_storepsrendition">true</prop> If the request is done through legacy calls, the background_legacy_calls.xml and custom_legacy_calls.xml command line files must be modified as well. Choosing Whether to Save PDT Files The PDT rendition of a document is the text file used specifically for term-hit highlighting. If you do not wish to store the PDT rendition of a document in the repository, please navigate to the repository folder System\Media Server\System Profiles and open the file legacy_to_pdf. Uncomment the following section: <PROP name="store PDF Text Rendition" type="string" token="doc_token_storepdtrendition">true</prop> 26 Document Transformation Services Administration Guide

27 Con guring Document Transformation Services If the request is done through legacy calls the background_legacy_calls.xml and custom_legacy_calls.xml command line files must be modified as well. Document Transformation Services Administration Guide 27

28 Con guring Document Transformation Services 28 Document Transformation Services Administration Guide

29 Chapter 3 Administering Document Transformation Services This chapter contains information about Document Transformation Services administration options. Administration tasks include the following: Attribute mappings from the source document to a PDF rendition (Embed Metadata) The repositories polled by Document Transformation Services Timing and operational parameters Administering Document Transformation Services through Documentum Administrator Some administration tasks for Document Transformation Services can now be done through the Content Transformation Services Administration component of Documentum Administrator. The CTS Administration component appears in Documentum Administrator if at least one instance is installed and configured on a repository to which it is connected. This check is done through executing the DQL/DFC call to find the presence of at least one cts_instance_info object in the repository. The following Document Transformation Services administration tasks can be performed through a Documentum Administrator: Viewing log files. Allows you to view any Document Transformation Services log files. Viewing details of an instance. Details included here include each CTS product that is configured for a repository (Document Transformation Services, Advanced Documentation Transformation Services, Media Transformation Services, Audio/Video Transformation Services, OCR Transformation Services, and Medical Imaging Transformation Services), the version number of each product, the name of the host machine for each product, it s current status (running or stopped), the time Document Transformation Services Administration Guide 29

30 Administering Document Transformation Services it was last started, the number of queued items for the instance, and the number of items processed by the instance. Controlling a CTS Instance. This includes starting, stopping, and refreshing an instance. Please note that performing any of these actions will apply to all CTS products running on the host. This is because all CTS products on a host use the same CTS Windows Service. Starting and stopping CTS Windows Service can also be done manually, on the host machine. See Starting and Stopping Document Transformation Services, page 31. Starting and Stopping the CTS Admin Agent In order to use the Content Transformation Services Administration component in Documentum Administration, it is necessary to have the CTS Admin Agent running on the CTS host machine. To start the CTS Admin Agent: 1. Log in to the Document Transformation Services host. 2. Go to the Windows Services utility located at Start Settings Control Panel Administrative Tools Services. 3. Highlight Documentum CTS Admin. Agent and click Start. - OR - 1. Navigate to C:\Program Files\Documentum\CTS\AdminAgent\bin. 2. Launch the startup.bat batch file. To stop the CTS Admin Agent: 1. Log in to the Document Transformation Services host. 2. Go to the Windows Services utility located at Start Settings Control Panel Administrative Tools Services. 3. Highlight Documentum CTS Admin. Agent and click Stop. - OR - 1. Navigate to C:\Program Files\Documentum\CTS\AdminAgent\bin. 2. Run the shutdown.bat batch file. 30 Document Transformation Services Administration Guide

31 Administering Document Transformation Services Starting and Stopping Document Transformation Services When you restart the Document Transformation Server host, the Document Transformation Server will start automatically. You may also start and stop the Document Transformation Server manually, using the following procedure. To start Document Transformation Services: 1. Log in to the Document Transformation Services host. 2. Go to the Windows Services utility located at Start Settings Control Panel Administrative Tools Services. 3. Highlight Documentum Content Transformation Services and click Start. - OR - 1. Navigate to C:\Program Files\Documentum\CTS\server_install\CTSService. 2. Launch the startcts.bat batch file. To stop Document Transformation Services: 1. Log in to the Document Transformation Services host. 2. Go to the Windows Services utility located at Start Settings Control Panel Administrative Tools Services. 3. Highlight Documentum Content Transformation Services and click Stop. - OR - 1. Navigate to C:\Program Files\Documentum\CTS\server_install\CTSService. 2. Run the stopcts.bat batch file. Transferring Document Attributes A document s attributes are its descriptive characteristics, such as name, title, author, creation date, object ID, or subject. You can set the values for some attributes. Other attributes, such as the document s creation date, are set by the system. Document Transformation Services lets you transfer these attributes to a document s PDF rendition (but not to a document s HTML rendition). You can then use the attributes for identification or tracking purposes after the PDF document is exported from the repository where the source document resides. Document Transformation Services Administration Guide 31

32 Administering Document Transformation Services Note: Some attributes, like repository ID, may not be visible when viewed through Document Info in Adobe Exchange. You can also transfer attribute information to custom Plug-ins, where the Plug-in needs to know certain information about a document (such as type, author, or source type). For example, you could write a Plug-in that looks for certain attributes identifying a document as a Standard Operating Procedure (SOP). If those attributes are found, the Plug-in prints a special cover page, or adds or subtracts context-sensitive information before the document is rendered into PostScript format. Transferring Document Attributes to PDF and Embedding Metadata To transfer attributes, you must edit the appropriate command line files of the Document Transformation Services. The following command line files are responsible for transferring the attributes from the source document to the PDF rendition: custom_legacy_calls.xml (used by the custom Plug-ins) embedpdfmetadata.xml (used by the transformation profiles for embedding the metadata) You define the attribute mapping for PDF renditions under the <PDF_DOC_INFO> tag of these command line files. The syntax is: value = object_alias.attribute[repeating_spec] An example would appear as follows: <PDF_DOC_INFO> <MetadataMapper name="dctmobjecttitle" value="title" token="doc_metadata_dctmtitle"/> </PDF_DOC_INFO> The attribute token is used internally by the server code, and has to be named with the prefix doc_metadata_ (e.g.: token=" doc_metadata_dctmtitle ) Table 3 1, page 33 explains the attribute mapping arguments: 32 Document Transformation Services Administration Guide

33 Administering Document Transformation Services Table 3-1. Attribute mapping arguments Argument key object_alias Description Can be an existing attribute or a user-defined attribute. For example: author, subject, title, producer. When omitted or specified as o, the object_alias indicates that the following attribute is that of a sysobject or one of its subtypes (the document being rendered). Other valid object_aliases are: attribute value Here are some examples of attribute mapping syntax. d (repository config object) s (server config object) q (attributes from special runtime-computed items) Refer to the Documentum Content Server Administrator s Guide for more information about configuration objects. In the case of o,s,d object aliases, attribute dynamically maps the attribute. In the case of the q object, the only currently available attributes are sentby, login_ticket, and username. For repeating attributes, value defines the repeating attribute separator (for example, a comma or a slash). If no separator is defined, and the attribute is repeating, Content Rendition Services maps only the first attribute in the series [element 0]. The first example shows an attribute where the object alias ( o ) is implied: <MetadataMapper name="subject" value="subject" token="doc_metadata_subject"/> The following example shows an attribute mapped with specified object alias. <MetadataMapper name="dctmsourcecontenttype" value="o.a_content_type" token="doc_token_sourcecontenttype"/> The following example shows a comma-separated list of keywords from sysobject. <MetadataMapper name="keywords" value="keywords[,]" token="doc_metadata_keywords"/> Document Transformation Services Administration Guide 33

34 Administering Document Transformation Services The following example shows a list of authors, separated by // (two forward slashes): <MetadataMapper name="author" value="authors[//]" token="doc_metadata_author"/> Opening New repository Sessions with Ticketed Logins You can write Plug-in applications that open another session with a repository in addition to a session currently running. For security reasons, you may wish to do this without requiring the Plug-in to send the user s password with the Connect method. Ticketed logins provide a way to do this. In a ticketed login, a connection request is sent to the Content Server using a ticket in place of the user s password. A ticket allows an application to open another session in the current repository as the current user without specifying the user s password. An application using a login ticket must connect as the same user that generated the ticket. The following example allows the assignment of a login ticket valid for five minutes for a second login to the repository (identified by DCTMrepositoryId) by the same user who logged in the first time (identified by DCTMRequestedBy). The repository, username, and login_ticket attributes provide the minimum information for connecting to a repository. DCTMrepositoryId = d.r_repository_id DCTMRequestedBy = q.sentby repository = s.object_name user_name = q.username login_ticket = q.login_ticket Note: Refer to the guide Content Server Fundamentals for more information about ticketed logins. Viewing the Attributes in the PDF Rendition To see the transferred attributes for a PDF rendition, choose Document Transformation Services in Adobe Acrobat. Altering Timing and Operational Parameters This sections that follow explain how to change some timing and operational parameters that can be changed. 34 Document Transformation Services Administration Guide

35 Administering Document Transformation Services To change timing and operation parameters: 1. Stop the Documentum Content Transformation Services service. 2. Change timing and operational parameters as desired. (Refer to the sections that follow for detailed information about Settings options.) 3. Restart the Documentum Content Transformation Services service. Controlling How Quickly Programs Time Out When Document Transformation Services is processing a request it calls external programs, such as Microsoft Word, as part of the process. There may be occasions when one of these programs fails, or simply runs longer than you want it to run. To control the resources consumed by an external program, Document Transformation Services includes an application timeout parameter. The value assigned to the parameter determines how long Document Transformation Services waits for an external program to complete before moving on to the next request. The timer starts when Document Transformation Services calls the external program. If Document Transformation Services calls Microsoft Word to print a PDF version of a document and that program does not complete within 30 seconds, Document Transformation Services abandons the request and checks the queue for the next request. When a rendition operation fails, Document Transformation Services sends a message reporting the failure to Document Transformation Services log file and also to the requester s Inbox. The default value for the application timeout parameter is 10 seconds Controlling the timeout interval is done through the corresponding plug-in configuration files. This is controlled by the following related tag in the plug-in s configuration file: <APPLICATION_WAIT_INTERVAL>10</APPLICATION_WAIT_INTERVAL> APPLICATION_MONITOR>true</APPLICATION_MONITOR> For example if we want to configure this value to 30 seconds for any Word file, modify the following tag of word.xml file (available under the folder \%CTS_HOME%\CTS\config\word\) as follows: <APPLICATION_WAIT_INTERVAL>30</APPLICATION_WAIT_INTERVAL> APPLICATION_MONITOR>true</APPLICATION_MONITOR> Document Transformation Services Administration Guide 35

36 Administering Document Transformation Services Controlling the Document Transformation Services Log Level The log level can be controlled by modifying the Levels of logger of log4j.properties available in the folder \%DCTM_USER_DIR%\config, for example, C:\Documentum\config. By default it is set to INFO level. To get more logging information, this level can be modified to DEBUG. 36 Document Transformation Services Administration Guide

37 Chapter 4 Transformation Pro les Document Transformation Services predefined profiles cover most of the common document transformation, such as document to PDF and document to HTML. Document Transformation Services enables system administrator to modify existing profiles or create new profiles. The following system profiles are responsible for the legacy calls for PDF rendition and HTML rendition requests. legacy_to_pdf legacy_to_html Also you may wish to modify a system profile if the current profile is unsuitable for your specification. Modifying a profile will customize it to your specifications. Understanding Command-line Files Command-line files are stored in the repository as XML files that can be used by the Transformation profiles as needed. When the target Plug-in is identified, Document Transformation Server translates the profile into a command-line file for the Plug-in. The command-line file contains detailed instructions for the Plug-in. It may also contain additional parameters that are not user-selectable. For example, a profile could be written to always create a PDF with full security. The resulting file format and many of its attributes could be controlled at the command level. Command-line files are specific to each Plug-in, since their capabilities vary. Each profile contains the profile name, a label (the text that displays in the client application), a description, required attributes, and supported source/target dm_format objects Profiles for which all parameters are defined contain only the name, label, description, and supported source and target formats. Each profile is linked to an actual XML command-line file for a given transformation. Command-line files do not need to be created for profiles that re-use other profiles. A lightweight profile that serves only to chain or sequence other profiles has no need for CommandFilePath entries. Since the DTD does not require their presence, no change Document Transformation Services Administration Guide 37