xml transformation services administration guide

EMC® Documentum®

XML Transformation ServicesVersion 6.5

Administration GuideP/N 300-007-277 A01

EMC CorporationCorporate Headquarters:

Hopkinton, MA 01748-91031-508-435-1000www.EMC.com

Copyright © 2007–2008 EMC Corporation. All rights reserved.

Published July 2008

EMC believes the information in this publication is accurate as of its publication date. The information is subject to changewithout notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONSOR WARRANTIES OF ANY KINDWITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLYDISCLAIMS 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.

All other trademarks used herein are the property of their respective owners.

Table of Contents

Preface ........................................................................................................................... 9

Chapter 1 XML Transformation Services Overview ................................................ 11What is Content Transformation Services?.................................................... 11Content Transformation Services scalability ............................................. 12

What is XML Transformation Services? ........................................................ 12XML Transformation Services components............................................... 12XML Transformation Services environment.......................................... 13XML Transformation Server ................................................................ 13Documentum Foundation Classes ....................................................... 13XML Transformation Services plug-in .................................................. 14

Transform handlers ................................................................................ 14How XML Transformation Services works ............................................... 15How XML Transformation Services creates PDF renditions ................... 15How XML Transformation Services creates HTML renditions................ 16

How XML Transformation Services creates CHM renditions ..................... 17Features of XML Transformation Services .................................................... 19Supported transformations by source and target formats .............................. 20

Chapter 2 Conguring XML Transformation Services ........................................... 23Configuring XML Transformation Services through DocumentumAdministrator ............................................................................................ 23Starting and stopping the CTS Administration Agent ............................... 24Accessing the configuration screen in DocumentumAdministrator ............ 25

Adding or removing repositories serviced by XMLTransformationServices ..................................................................................................... 25Defining file formats and DOS extensions .................................................... 26Configuring filters ...................................................................................... 28Adding product names to the product filter ............................................. 29Configuring other DITA filters................................................................. 30Configuring other DocBook filters ........................................................... 33

Configuring Inbox notifications ................................................................... 35Configuring XTS with custom style sheet ..................................................... 37Configuring XTS to transform DITA content with peer links.......................... 37

Chapter 3 Administering XML Transformation Services ........................................ 41Administering XML Transformation Services throughDocumentum Administrator ....................................................................... 41Starting and stopping the CTS Administration Agent ............................... 42

Starting and stopping XML Transformation Services..................................... 43Altering timing and operational parameters ................................................. 43Controlling the logging level ................................................................... 44

Managing multiple servers.......................................................................... 44

EMC Documentum XML Transformation Services Version 6.5 Administration Guide 3

Table of Contents

Changing the CTS Service user after installation ........................................... 44Changing the CTS administrator password .................................................. 45Conguring the queue marker mechanism to manage queue itemsign-off ...................................................................................................... 45Working with the CTS Activity Template in Documentum ProcessBuilder....................................................................................................... 46Making the CTS Activity Template available to users ................................ 46Making transformation profiles available for use with CTSActivity Template ................................................................................... 47Transformation profiles with no parameters ......................................... 48

Using the CTS Activity Template ............................................................. 48Using the CTS Reporting Tool ..................................................................... 50Enabling and disabling the CTS Reporting Tool ........................................ 51Viewing the CTS Reporting Tool report.................................................... 51

Managing the transformation queue ............................................................ 52Viewing transformation requests in the queue .......................................... 53Changing a queue item’s priority ............................................................. 53Viewing details of a queue item ............................................................... 54Deleting a pending queue item ................................................................ 55Configuring additional queue management fields .................................... 55Removing a queue management field ...................................................... 56

Migrating existing profiles .......................................................................... 57Viewing log file of migrated profiles ........................................................ 57

Selecting Internet Protocol version ............................................................... 58Configuring XTS to transform XML content ................................................. 58

Chapter 4 Administering Content Transformation Services Web Services ............ 61What are CTS web services.......................................................................... 61Profile service......................................................................................... 61Operations related to this service ......................................................... 62

Transformation service............................................................................ 62Operations related to this service ......................................................... 63

Web services and Document Foundation Services (DFS)................................ 63Content Transformation Services web services architecture .......................... 64Asynchronous and synchronous transformation........................................... 65Synchronous requests ............................................................................. 65CTS asynchronous architecture................................................................ 66

Configuring CTS WebServices instance ........................................................ 66Configuring CTS WebServices instance for JBoss ...................................... 66Verifying configuration of CTS web services......................................... 67Verifying CTS web service file are accessible ........................................ 67Verifying deployment of EAR files....................................................... 68Verifying contents of transformation.properties file .............................. 68Verifying preferences.xml file is updated with configuredrepository .......................................................................................... 68Location of realtime requests log files .................................................. 69

Configuring CTS WebServices instance for other supportedapplications............................................................................................ 69Locating CTS WebServices log file ........................................................... 72

Chapter 5 Working with Proles ............................................................................ 73Understanding command-line files .............................................................. 73Building and modifying profiles with Profile Editor...................................... 74

4 EMC Documentum XML Transformation Services Version 6.5 Administration Guide

Table of Contents

Editing a profile ..................................................................................... 74Building a new profile ............................................................................ 75Building a chain profile........................................................................... 77Building a parallel profile........................................................................ 79

Modifying profiles manually ....................................................................... 81Using DQL in profiles ................................................................................. 81The dql attribute value syntax ................................................................. 82DQL guidelines ...................................................................................... 82DQL query examples .............................................................................. 82Querying the r_object_id attribute ........................................................... 83

Chapter 6 Performing Transformations ................................................................. 85Transforming DITA files.............................................................................. 85Transforming DocBook files ........................................................................ 87Transforming DocBook files to CHM ....................................................... 87Transforming DocBook files to HTML...................................................... 89Transforming DocBook files to PDF ......................................................... 91

Viewing renditions ..................................................................................... 92

Chapter 7 Troubleshooting .................................................................................... 93Error events and log files............................................................................. 93A transformation request fails ..................................................................... 94A profile error occurs.................................................................................. 94XML Transformation Server cannot add a rendition to a particularformat........................................................................................................ 95XML Transformation Server cannot log in to the repository ........................... 95CTS Administration Agent gives AGENT_INACCESSIBLE message.............. 96Content Transformation Services fails to function ......................................... 97Locating application server working folder .................................................. 97


Table of Contents

List of Figures

Figure 1. Typical XML Transformation Services installation............................................. 13Figure 2. Processing a request for a PDF rendition .......................................................... 16Figure 3. Processing a request for an HTML rendition..................................................... 17Figure 4. Processing a request for a CHM rendition ........................................................ 19Figure 5. Content Transformation Services Web Services Architecture.............................. 64


Table of Contents

List of Tables

Table 1. XML Transformation Services features ............................................................. 19Table 2. Supported transformations with XML Transformation Services by

source and target formats............................................................................ 20Table 3. File format attributes ...................................................................................... 26Table 4. Documentum format mapping ........................................................................ 28Table 5. Inbox notification settings ............................................................................... 35


Table of Contents


Preface

This guide provides step-by-step procedures for configuring and administering Documentum XMLTransformation Services. This manual also includes information about modifying profiles to extendthe functionality of XML Transformation Services.

You can find additional information about XML Transformation Services in the following documents:• XML Transformation Services Installation Guide• XML Transformation Services Release NotesSee the appropriate Documentum product documentation for information on related Documentumproducts. For example, many administration and configuration tasks for XML TransformationServices are best performed through Documentum Administrator; consult the DocumentumAdministrator User Guide for guidance.

Intended audienceThe primary audience for this guide is the system administrator who maintains thissoftware. The secondary audience is the system integrator who wishes to extend XMLTransformation Services functionality.

Familiarity with Microsoft Windows and the Documentum system is essential.

Revision historyThe following changes have been made to this document.


Preface

Revision date Description

July 2008 Initial publication for version 6.5 product release.


Chapter 1XML Transformation Services Overview

This chapter contains a brief overview of XML Transformation Services. It gives a basic descriptionof the Documentum environment and relates the XML Transformation Services components withinthe installation.

This chapter contains the following sections:• What is Content Transformation Services?, page 11• What is XML Transformation Services?, page 12• Features of XML Transformation Services, page 19• Supported transformations by source and target formats, page 20

What is Content Transformation Services?Content Transformation Services (CTS) is a suite of Documentum server products thatperform transformations and analysis on repository content. CTS includes these mainproducts:• Advanced Document Transformation Services (ADTS)• Document Transformation Services (DTS)• Media Transformation Services (MTS)• XML Transformation Services (XTS)Additional components are available for some of these products. For example, MediaTransformation Services may have additional transformation services installed, suchas Audio/Video Transformation Services (AVTS). These components supplementthe features already provided by the base product, according to your organization’srequirements.


XML Transformation Services Overview

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 meansthat stopping or starting the CTS service stops or starts all the CTS products on thathost. For example, if your CTS host contains XML Transformation Services and MediaTransformation Services, stopping the CTS service stops both products.

Each CTS product can be configured for multiple repositories. If you have one installationof a product on a host, that installation can be configured against multiple repositories.

CTS scalability also allows for several instances of Content Transformation Servicesproducts on different hosts to be configured for the same repository. This means thatyour installation can take either of two forms: one with identical plug-in capabilities,or one with different plug-in capabilities.

To enable this functionality, Content Transformation Services has format awareness.Format awareness is the ability for a Content Transformation Services product torecognize which file formats it is capable of processing. Items that cannot be processedsuccessfully will be removed from the queue automatically. A check for unprocesseditems is performed periodically.

What is XML Transformation Services?XML Transformation Services is server software that generates copies of documents inPortable Document Format (PDF), HyperText Markup Language (HTML), ZIP, andCompiled HTML Help (CHM). You can use Documentum client applications to request arendition of a document stored in a Documentum repository.

Designed primarily for technical publication organizations, XML TransformationServices is part of a seamless approach to storing, managing, and transforming XML,DITA, and DITAMAP content.

Refer to the XML Transformation Services Release Notes for details about the XML standardssupported in this release.

XML Transformation Services components

XML Transformation Services is an added component to your basic Documentuminstallation that includes Content Server and defined repositories with file stores. Thefollowing sections detail the main components that comprise a XML TransformationServices installation.



XML Transformation Services environment

Figure 1, page 13 shows a typical XML Transformation Services installation on theDocumentum platform.

Figure 1. Typical XML Transformation Services installation

XML Transformation Server

XML Transformation Services integrates with Documentum Content Server to process,store, and manage files within the Documentum schema. When users import files orrequest file transformations, the Content Server stores those register and request objectsin a queue. The XML Transformation Server will poll that queue intermittently, lookingfor register and request objects. The file is then passed to the appropriate TransformationService plug-in for processing.

When the processing is complete, the XML Transformation Server updates the originalobjects with new renditions or creates the new objects, as requested. The objects aresaved to the repository and the requests are removed from the queue. The objects arethen ready for use.

Documentum Foundation Classes

The Documentum Foundation Classes (DFC) are a set of Java classes that provideaccess to Content Server functionality. Web-based applications, such as Digital Asset



Manager and Web Publisher, make calls directly to the DFC or indirectly through theWeb Development Kit (WDK).

DFC must be installed on the XML Transformation Services host. If you are installingXML Transformation Services on a host that already has the DFC, XML TransformationServices may be able to use the existing DFC, provided they are the correct version.

The XML Transformation Services installer checks for existing DFC on the host. If theDFC are detected, they will be replaced by the version included with the installer.Refer to the relevant version of the Documentum System Migration Guide available at theDocumentum Download Center at https://emc.subscribenet.com/control/dctm/index formore information on migration issues. Follow the Documentum Foundation >Documentation for Documentum 6.5 link.

Any applications that were dependent upon the older version of the DFC will haveto be upgraded as well. For more information on the DFC and their effect on otherapplications, refer to your specific Documentum application documentation.

If your version is newer than the DFC included with the installer, it will be refreshed.

XML Transformation Services plug-in

The XML Transformation Services plug-in enables users to transform a variety of filesfrom one format to another (for example, from XML to PDF or HTML).

During an installation of XML Transformation Services, this plug-in is installed:• XPUB — transforms XML (based on DocBook and DITA standards), DITA, and

DITAMAP files to PDF, HTML, ZIP, or CHM; DITAMAP files to Java Help, EclipseHelp, RTF, and DocBook; and custom XML to PDF.

Plug-ins are extensible. You can configure plug-in types and formats, and you canadd new plug-ins to the system to support new file formats as required. Informationabout creating and adding new plug-ins is contained in the Content TransformationServices Product Development Guide, or contact your Documentum account or supportrepresentative for more information.

Transform handlers

Unique to XML Transformation Services is the use of transform handlers. While otherContent Transformation Services plug-ins perform transformations directly, the XPUBplug-in delegates transformation requests to the transform handlers. Each doctypefamily supported by XML Transformation Services has their own transform handler.

The following transform handlers are installed with XML Transformation Services:


https://emc.subscribenet.com/control/dctm/index


• DITA transform handler (DefaultDitaOT13Handler)

This transform handler is designed to work with DITA Open Toolkit version 1.3.x.• DocBook transform handler (DefaultDocBookHandler)

This transform handler transforms DocBook XML content using DocBook XSLstylesheets.

• XML transform handler (DefaultXMLToPDFhandler)

This transform handler transforms any custom XML to PDF.

(The customer provides the styles sheet required to generate XSL-FO content.)

How XML Transformation Services works

The following sections detail how XML Transformation Services creates renditions inPDF, HTML, and CHM.

How XML Transformation Services creates PDF renditions

The following steps describe how XML Transformation Services produces PDFrenditions in response to client requests:

1. The client application sends the rendition request to the Documentum ContentServer.

Note: XML Transformation Services modifies the document object, so it cannotprocess locked (checked out) documents.

2. Content Server stores the request in a queue called dm_queue.

3. XML Transformation Server polls dm_queue at predefined intervals, and retrievesany pending requests.

4. When XML Transformation Services finds a PDF rendition request in the queue, itchecks the input_doctype_family name token to distinguish between a DITA andDocBook file. The request is passed to the appropriate transform handler for thedocument.

5. The transform handler generates a PDF rendition based on what the default profilesspecify.

6. Content Server adds the PDF rendition to the object in the repository.An object represents a parent file, with all of its associated graphics, text, andrenditions, in the repository. Once a rendition has been added to the object, users



can view the rendition from the client application.Each time a transformation is performed, an additional rendition is created for thesource file.

Figure 2, page 16 illustrates this rendition process.

Figure 2. Processing a request for a PDF rendition

How XML Transformation Services creates HTML renditions

The following steps describe how XML Transformation Services produces HTMLrenditions in response to client requests:

1. The client application sends the rendition request to the Content Server.

Note: XML 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.


4. When XML Transformation Services finds an HTML rendition request in the queue,it checks the input_doctype_family name token to distinguish between a DITA andDocBook file. The request is passed to the appropriate transform handler.formatof the document.

5. XML Transformation Services invokes the corresponding application to open thefile and then saves an HTML version.



• If the result is a single HTML file, XML Transformation Services sends this fileto the Content Server.

• If the result consists of multiple files (for example, HTML, graphics, and XMLfiles), XML Transformation Services creates a Zip file containing these files,and sends the Zip file to Content Server. The Zip file includes any folders theapplication creates to contain these files.

6. Content Server adds the HTML or Zip file to the repository as a rendition of thedocument object.An object represents a parent file, with all of its associated graphics, text, andrenditions, in the repository. Once a rendition has been added to the object, userscan view the rendition from the client application.Each time a transformation is performed, an additional rendition is created for thesource file.


Figure 3. Processing a request for an HTML rendition

How XML Transformation Services creates CHMrenditions

The following steps describe how XML Transformation Services produces CHMrenditions in response to client requests:

1. The client application sends the rendition request to the Content Server.



Note: XML 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.


4. When XML Transformation Services finds a CHM rendition request in the queue,it checks the input_doctype_family name token to distinguish between a DITAand DocBook file. The request is passed to the appropriate transform handler forthe document.

5. XML Transformation Services invokes the corresponding application to generate thedesired rendition for the XML content and then saves an CHM version.• If the result is a single-file rendition, XML Transformation Services sends this file

to the Content Server.• If the result consists of multiple files (for example, HTML, graphics, and XML

files), XML Transformation Services creates a Zip file containing these files,and sends the Zip file to Content Server. The Zip file includes any folders theapplication creates to contain these files.

6. Content Server adds the single file to the repository as a rendition of the documentobject.An object represents a parent file, with all of its associated graphics, text, andrenditions, in the repository. Once a rendition has been added to the object, userscan view the rendition from the client application.Each time a transformation is performed, an additional rendition is created for thesource file.




Figure 4. Processing a request for a CHM rendition

Features of XML Transformation ServicesThe following are the features that XML Transformation Services offers.

Table 1. XML Transformation Services features

Feature Comments

Runs as a Windows Service andintelligently handles exceptions raisedby native applications.

Transforms XML, DITA, andDITAMAP files into PDF, HTML,ZIP*, Compiled HTML Help (CHM);Eclipse Help**, Java Help**, RTF**,DocBook.**

XML source files in DITA and DocBookstandards are supported.

Transform XML to PDF. The target output is PDF only.

Filters the output based on a varietyof parameters.

By default, filters for operating systems,audience levels, revisions, and product namesare available. These filters are configurable.See Configuring filters, page 28 for details.

Creates a new rendition each time afile is transformed.



Feature Comments

Transforms a document as part of abusiness workflow process using theCTS Activity Template.

CTS Activity Template is included. Profileconfiguration required. See Working withthe CTS Activity Template in DocumentumProcess Builder, page 46 for details. See XMLTransformation Services Installation Guide forinstallation instructions.

Integrates with entire Documentumproduct suite.

* ZIP output is valid for DITA source files only.

**Output is valid for DITAMAP source files only.

Supported transformations by source andtarget formats

The supported transformations depend upon the installation of a variety of applicationson the XML Transformation Services host. For more information, see the XMLTransformation Services Release Notes.

With the required supporting applications installed, XML Transformation Services canperform the following transformations.

Table 2. Supported transformations with XML Transformation Services by source andtarget formats

Source format (input) XML standard Target formats(output)

DITA PDF, HTML, ZIPXML

DocBook PDF, HTML,Compiled HTMLHelp (CHM)

XML XML Schema PDF



Source format (input) XML standard Target formats(output)

DITA DITA PDF, HTML, ZIP

DITAMAP DITA PDF, HTML,Compiled HTMLHelp (CHM), JavaHelp, Eclipse Help,RTF, and DocBook


Chapter 2Conguring XML TransformationServices

This chapter contains instructions for configuring XML Transformation Services. The followingsections are included in this chapter:

• Configuring XML Transformation Services through Documentum Administrator, page 23• Adding or removing repositories serviced by XML Transformation Services, page 25• Defining file formats and DOS extensions, page 26• Configuring filters, page 28• Configuring Inbox notifications, page 35• Configuring XTS with custom style sheet, page 37• Configuring XTS to transform DITA content with peer links, page 37

Conguring XML Transformation Servicesthrough Documentum Administrator

Many configuration tasks for XML Transformation Services can now be done through theCTS Administration component of Documentum Administrator. You must have accessto Documentum Administrator and the repositories to which XML TransformationServices is configured.

The CTS Administration component appears in Documentum Administrator if at leastone instance is installed and configured on a repository to which it is connected. Thischeck is done through executing the DQL/DFC call to find the presence of at least onects_instance_info object in the repository.

The following XML Transformation Services configuration tasks can be performedthrough the Documentum Administrator client, in the CTS Administration Node:


Conguring XML Transformation Services

• Change the system operator user. The system operator is the name of the user whoreceives messages from an instance of XML Transformation Services.

If XML 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 theXML Transformation Server system operator (sysOpUser). The event appears as anerror message in the sysOpUser’s Inbox.

• Change the user for repository login.• Change the polling interval. The polling interval is the amount of time in seconds

that the instance will wait between polls.

When document processing (transformation) is requested, Content Servercreates queue items and appends them to the dm_mediaserver queue ordm_autorender_win31 queue, depending on the type of request. XMLTransformation Server uses a queue polling mechanism to look for items in thequeue that it has to process. When XML Transformation Server finds items in any ofthese queues, it proceeds with processing.

• Change the logging level. The logging level value controls how much informationwill be recorded in the CTS log files, which XML Transformation Services uses. Logfiles can be used to troubleshoot the system.

• Change the system notification setting. The notification setting controls whethersuccess notifications should be sent to each individual user requesting atransformation through a CTS product.

• Change the maximum number of queue items. This value controls how many itemsthe XML Transformation Services instance adds for processing each time it pollsthe queue.

• Change the queue item expiry. This value controls the amount of time an item willbe sitting in a queue before being deleted from the queue.

The Documentum Administrator User Guide provides more information about theseconfiguration tasks.

Starting and stopping the CTS Administration Agent

In order to use the Content Transformation Services Administration component inDocumentum Administrator, it is necessary to have the CTS Admin Agent running onthe CTS host machine. The Admin Agent can be stopped or started either from theWindows Start menu, or by running a batch file.

To start/stop the CTS Admin Agent through the Start menu:1. Log in to the XML Transformation Services host.



2. Go to the Windows Services utility located at Start > Settings > Control Panel >Administrative Tools > Services.

3. Select Documentum CTS Admin Agent.

4. To start the Admin Agent, click Start.To stop the Admin Agent, click Stop.

To start/stop the CTS Admin Agent by running the batch le:1. Log in to the XML Transformation Services host.

2. Navigate to C:\Program Files\Documentum\CTS\Admin Agent\bin.

3. To start the Admin Agent, run the startup.bat file.To stop the Admin Agent, run the shutdown.bat file.

Accessing the conguration screen in DocumentumAdministrator

You can perform the tasks outlined in Configuring XML Transformation Servicesthrough Documentum Administrator, page 23 through the configuration screen inDocumentum Administrator. Ensure that the CTS Admin Agent is running.

To access the conguration screen:1. Log in to Documentum Administrator.

2. Select the Content Transformation Services node under Administration.

3. Select the CTS instance you would like to configure.

4. Select Tools > Content Transformation Services > Configure.Consult the Documentum Administrator User Guide for information about configurationtasks.

Adding or removing repositories serviced byXML Transformation Services

During installation, XML Transformation Services is configured to communicate withsingle or multiple repositories. You can add or remove a repository by running theXML Transformation Services Configurator (accessible through the Windows menu at



Start>Programs>Documentum>XTS Configuration Utility). For information on theConfigurator and how to run it, see the XML Transformation Services Installation Guide.

Note: You must have SuperUser privileges for a repository in order to add or removesupport for XML Transformation Services.

Dening le formats and DOS extensionsYou must define file formats and DOS file extension pairs in the repository for all sourcedocument types that you want XML Transformation Services to recognize. In addition, ifthe DOS file extension differs from the Documentum format name, you must updatethe FormatMapperService.xml config file.

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, as listed in Table 3, page 26.

Table 3. File format attributes

Field Value

Name Name of the format object

Description Description of the format

Default File Extension Examples of valid file extensions are:• dita for DITA topic files• ditamap for DITA map files• xml for XML (DITA or DocBook) files

COM Class ID Component Object Model (COM) registry ID for theformat

MIME Type The Multimedia Internet Mail Extension (MIME)designation for the content type



Field Value

Windows Application Name of an application to launch when users selecta document in the format represented by the formatobject

Is Hidden Used by client applications

Macintosh Creator* Information used internally for managing Macintoshresource files

Macintosh Type* Information used internally for managing Macintoshresource files

* The Macintosh Creator and Type values are necessary for users to access files inthis format from Macintosh clients.

5. If the format is indexable, define the indexing options.

a. Select Can Be Indexed.

b. To index with a filter, click Index with Filter and select the filter from the list box.By default, all formats installed with the Content Server use the universal filter.

c. To index with a rendition, click Index with Rendition and select the renditionformat from the list box.This is the format in which the document will be indexed if its original format isnot used for indexing. If you are indexing the PDF text rendition of documentsin this format, set this to pdftext.

6. Click Create.A confirmation page appears. You can create a new template for this format byselecting Create New Template for this Format.

The following procedure is required only if the DOS file format differs from theDocumentum format name in Content Server. See Table 4, page 28 for a listing of formatnames used in Documentum systems.

To update the FormatMapperService cong le:1. Navigate to %CTS_HOME%\config.

2. Open the FormatMapperService.xml file in a text editor.

3. Add the format to the <CTSHandlerList> section, using the following syntax:<FormatMapper CTSFormat="<dos extension>" DocumentumFormat="<format name in Content Server>"/>

For example, the entry for DITA topic files is:<FormatMapper CTSFormat="dita" DocumentumFormat="ditatopic"/>

4. Save and close the FormatMapperService.xml file.



Table 4, page 28 lists some examples of the format mapping used in Documentumsystems. Use these format names in DQL.

Table 4. Documentum format mapping

Format Documentum name

DITA ditatopic

DITAMAP ditamap

XML xml

Conguring ltersFilters allow you to configure the output to include or exclude specific content that hasbeen tagged within the source document. For example, a user guide may have contentthat applies to specific operating systems on which the application is installed. If thecontent pertaining to those operating systems is tagged as such within the source file, theoutput can be filtered accordingly.

XML Transformation Services is configured out of the box with the following four filters:• profile_os

The following operating systems are available: Windows, Linux, HP-UX, Solaris,and Mac.

• profile_audience

The following audience levels are available: Expert, Intermediate, and Beginner.• profile_revision

The following revision names are available: New, Changed, Deleted, and Final.• profile_product

No names exist for this filter. You must add the product names that apply to yourorganization.

If any of these default filters are appropriate for your organization, you must ensure thatthe source documents are profiled accordingly. To use the operating system profile, forinstance, you must tag sections within your source documents with operating systemnames. Consult the documentation for your authoring system to determine how toprofile your source documents.

For many organizations, these filters will require modification, or new filters will beneeded.



One transformation profile controls all DITA filters, while three different profiles arerequired for DocBook transformations. Separate procedures are provided for both DITAand DocBook filter configurations.

This section covers the following topics:• Adding product names to the product filter, page 29• Configuring other DITA filters, page 30• Configuring other DocBook filters, page 33

Adding product names to the product lter

Since each organization will have a unique set of product names for which to filter, youmust add the appropriate product names to the transformation profiles.

Note: By default, the profiles have no product names specified. If you do not addproduct names as outlined below, users can simply enter the product name in a text boxwhen they perform transformations. However, this approach could lead to user errorsif incorrect product names are entered. Configuring the product names in the profilesis highly recommended.

To add product names to appear in the product lter list box:1. Log in to the repository using an appropriate application.

2. Navigate to /System/Media Server/Profiles.

3. Check out or export the ProfileSchema.dtd file.If you export the file, you only need to do so the first time you modify a profile.Leave the DTD file in your checkout directory so that the profiles you check out inthe future can reference the DTD.

4. Check out the appropriate profile:• For all DITA transformations, select dita_transform.xml.• For DocBook transformations, select the docbook_transform_chm.xml,

docbook_transform_html.xml, or docbook_transform_pdf.xml, depending onthe transformations your organization will be using.

Note: If these files are not immediately visible, select Show All Objects andVersions from the Show list box.

5. Open the profile in an XML or text editor.

6. Locate the profile_product parameter. Change the controltype from "text” to"listbox”.

7. Add <ValueList> tokens to the profile_product parameter.



For example, if you want to filter content based on model number, you could addvalues as follows:<Parameter name="profile_product"

label="Product Filter"controltype="listbox"datatype="string"isRequired="false"description="Select any Products You wish...">

<ValueList><Value label="Model A">Model A</Value><Value label="Model B">Model B</Value><Value label="Model C">Model C</Value><Value label="Model D">Model D</Value></ValueList></Parameter>

8. Save your changes.

9. Check in the profile.

10. Stop and restart the transformation server service.The correct product names will now appear in the product list box when users arerequesting transformations.

Conguring other DITA lters

The dita_transform.xml profile file controls the filters for all DITA transformations.

To modify an existing DITA lter:1. Log in to the repository using an appropriate application.



4. Check out the dita_transform.xml file.

Note: If this file is not immediately visible, select Show All Objects and Versionsfrom the Show list box.


6. Locate the filter parameter you wish to modify within the <Transcodings> section.For example, the revision filter appears as follows:<Parameter name="profile_revision"

label="Revision Filter"



controltype="listbox"datatype="string"isRequired="false"description="Select Any Revision Flags You Wish to

Exclude"><ValueList><Value label="New">New</Value><Value label="Changed">Changed</Value><Value label="Deleted">Deleted</Value><Value label="Final">Final</Value></ValueList></Parameter>

7. Add, modify, or delete a value within the list, being careful to follow the propersyntax.For example, you could change the values for profile_revision, as follows:<Parameter name="profile_revision"

label="Revision Filter"controltype="listbox"datatype="string"isRequired="false"description="Select Any Revision Flags You Wish to

Exclude"><ValueList><Value label="First draft">First draft</Value><Value label="Technical review">Technical review</Value><Value label="Approved">Approved</Value></ValueList></Parameter>



10. Stop and restart the transformation server service.The modified values will now appear when users request transformations for DITA files.

To add a new lter for DITA source les:1. Log in to the repository using an appropriate application.



4. Check out the dita_transform.xml file.



6. Add a parameter for the filter you wish to add.For example, to add a filter based on application servers, the new parameter mightappear as follows:<Parameter name="profile_appserver"

label="Application Server Filter"controltype="listbox"datatype="string"isRequired="false"description="Select an application server to exclude">

<ValueList><Value label="BEA">BEA</Value><Value label="Oracle">Oracle</Value><Value label="Sun One">Sun One</Value><Value label="Tomcat">Tomcat</Value></ValueList></Parameter>



9. Navigate to /System/Media Server/Command Line Files.

10. Check out the dita_transform_command.xml file.



12. In the <input_properties> section, add the new filter. This illustrates the entry forthe application server example:<property name="profile_appserver" value=""/>

13. In this same file, add an entry to the <conditional_params> section. Continuing theapplication server example, this addition would appear as follows:<param name="appserver" use-property="profile_appserver"/>



16. Stop and restart the transformation server service.The new filter will now appear when users request transformations for DITA files.


Conguring other DocBook lters

Three profile files handle DocBook transformations, based on the output format:• docbook_transform_chm• docbook_transform_html• docbook_transform_pdfEach of these profiles contains a unique set of parameters. They also include the standardfour filters as for DITA files.

To modify an existing DocBook lter:1. Log in to the repository using an appropriate application.



4. Check out the docbook_transform file you wish to modify.



6. Locate the filter parameter you wish to modify within the <Transcodings> section.For example, the audience filter appears as follows:<Parameter name="profile_audience"

label="Audience Filter"controltype="listbox"datatype="string"isRequired="false"default="">

<ValueList><Value label="Expert">Expert</Value><Value label="Intermediate">Intermediate</Value><Value label="Beginner">Beginner</Value></ValueList></Parameter>

7. Add, modify, or delete a value within the list, being careful to follow the propersyntax.For example, you could change the values for profile_audience, as follows:<Parameter name="_audience"

label="Audience Filter"controltype="listbox"



datatype="string"isRequired="false"default="">

<ValueList><Value label="User">User</Value><Value label="Administrator">Administrator</Value><Value label="Developer">Developer</Value></ValueList></Parameter>



10. Stop and restart the transformation server service.The modified values will now appear when users request transformations for DocBookfiles.

To add a new lter for DocBook source les:1. Log in to the repository using an appropriate application.



4. Check out the docbook_transform file for which to add a filter.



6. Add a parameter for the filter you wish to add.For example, if your documents contain different regulatory statements pertainingto different countries, you might require a country filter. Such a parameter mightappear as follows:<Parameter name="profile_country"

label="Country Filter"controltype="listbox"datatype="string"isRequired="false"description="Include content specific to this country">

<ValueList><Value label="USA">USA</Value><Value label="Canada">Canada</Value><Value label="Mexico">Mexico</Value></ValueList></Parameter>


9. Navigate to /System/Media Server/Command Line Files.

10. Check out the docbook_transform_command.xml file.



12. In the <input_properties> section, add the new filter. This illustrates the entry for thecountry example:<property name="profile_country" value=""/>

13. In this same file, add an entry to the <conditional_params> section. Continuing thecountry example, this addition would appear as follows:<param name="country" use-property="profile_country"/>



16. Stop and restart the transformation server service.The new filter will now appear when users request transformations for DocBook files.

Conguring Inbox noticationsWhen transformation requests fail, the XML Transformation Server sends notifications tothe Inbox of the repository user. By default, success notifications are not sent. However,these default behaviors can be configured using the procedures in this section.

The behavior of success and failure notifications differs slightly. While successnotifications can be suppressed for all users, failure notifications are sent to admin usersregardless of the setting. Table 5, page 35 outlines these behaviors.

Table 5. Inbox notication settings

Notification Setting User(s) notified

Success Yes Regular user

No none


Notification Setting User(s) notified

Failure Yes Regular user and admin user

No Admin user

To modify the conguration of success notications:1. Navigate to %CTS_HOME%\config.

2. Open the CTSServerService.xml file in a text editor.

3. To turn on notifications for successful transformations, you need to set thenotifySuccessMessage parameter to the following:<CTSServer AttributeName="notifySuccessMessage" AttributeValue="YES"/>

To turn off notifications for successful transformations, you need to set thenotifySuccessMessage parameter to the following:<CTSServer AttributeName="notifySuccessMessage" AttributeValue="NO"/>

Note: There are two <QueueProcessorContext> tags for each repository that isconfigured. You must modify the notifySuccessMessage parameter within each<QueueProcessorContext> tag.

4. Save and close the CTSServerService.xml file.

To modify the conguration of failure notications:1. Navigate to %CTS_HOME%\config.

2. Open the CTSServerService.xml file in a text editor.

3. To turn on notifications for failure transformations, you need to set thenotifySuccessMessage parameter to the following:<CTSServer AttributeName="notifyFailureMessage" AttributeValue="YES"/>

To turn off notifications for failure transformations, you need to set thenotifySuccessMessage parameter to the following:<CTSServer AttributeName="notifyFailureMessage" AttributeValue="NO"/>

Note: There are two <QueueProcessorContext> tags for each repository that isconfigured. You must modify the notifySuccessMessage parameter within each<QueueProcessorContext> tag.

4. Save and close the CTSServerService.xml file.



Conguring XTS with custom style sheetThe XML to PDF transformation uses the "Transform XML to PDF” profile. Newparameters need to be configured for this profile.

To congure XTS with custom style sheet:1. Locate the %CTS_HOME%\config\xpub.xml file.

2. Locate the <STYLESHEET> section.

3. Update the <STYLESHEET> node corresponding to "XML" handler to point to thenew file on your local system.

<STYLESHEET handler="XML" name="DEFAULT" fileref="C:\PROGRA~1\DOCUME~1\CTS\xts\xsl\default.xsl">

To congure parameter for the "Transform XML to PDF” prole:1. Check out the "xml_transform_pdf.xml” profile from the following folder in the

repository: /System/Media Server/Profiles.

2. Open the profile in an XML or text editor. Make the necessary changes and savethe file.

3. Locate the <Transcoding> tag and add the new parameter(s) as required.

4. Save and check in the file.

5. Check out the "xml_transform_pdf_command.xml” command line file from thefollowing folder in the repository: /System/Media Server/Command Line Files.

6. Locate the <xslt_params format="pdf"> section. For each of the parameters that youadd in Step 2, add a new tag, using the new parameter name:<param name="new_xslt_param_name1" use-property=" new_xslt_param_name1"/><param name="new_xslt_param_name2" use-property=" new_xslt_param_name2"/></xslt_params>


8. Restart the Documentum Content Transformation Services service.

Conguring XTS to transform DITA contentwith peer links

You need to configure XTS to transform DITA content with peer links:


To congure XTS to transform DITA content with peer links:Perform ONE of the following:

1. Check out the "dita_transform_command.xml” command line file from the followingfolder in the repository: /System/Media Server/Command Line Files.

2. Locate the following section:

<drl_resolver_enabled token="doc_token_drlresolver" value="true">

<param name="parse@xref@href" value="cross"/><param name="parse@link@href" value="cross"/><param name="parse@*@conref" value="con"/><param name="file_types" value="xml,dita,ditamap"/><param name="brokenlink" value="/Administrator/broken.dita"/>



param name="depth" value="1"/>

</drl_resolver_enabled>

3. Move your current configuration elements from version SP5 located at"${documentum.dir}\CTS\xts\DITA-OT1.3\lib\drlresolver.properties” to thesection in Step 2.


5. Remove the following lines:• <antcall target="resolve-drl"></antcall> from ${DITA-OT}\build.xml• <task target name="resolve-drl"> from ${DITA-OT}\build_preprocess.xml

6. Save the changes.

7. Restart the Documentum Content Transformation Services service.OR

1. Check out the "dita_transform_command.xml” command line file from the followingfolder in the repository: /System/Media Server/Command Line Files.

2. Locate the following line:<drl_resolver_enabled token="doc_token_drlresolver" value="true">

3. Change the value from "true” to "false”.



5. Restart the Documentum Content Transformation Services service.


Chapter 3Administering XML TransformationServices

This chapter contains information about XML Transformation Services administration options. Thefollowing sections are included in this chapter:

• Administering XML Transformation Services through Documentum Administrator, page 41• Starting and stopping XML Transformation Services, page 43• Altering timing and operational parameters, page 43• Managing multiple servers, page 44• Changing the CTS Service user after installation, page 44• Changing the CTS administrator password, page 45• Conguring the queue marker mechanism to manage queue item sign-off, page 45• Working with the CTS Activity Template in Documentum Process Builder, page 46• Using the CTS Reporting Tool, page 50• Managing the transformation queue, page 52• Migrating existing profiles, page 57• Selecting Internet Protocol version, page 58• Configuring XTS to transform XML content, page 58

Administering XML Transformation Servicesthrough Documentum Administrator

Some administration tasks for XML Transformation Services can now be done throughthe Content Transformation Services Administration component of DocumentumAdministrator. The CTS Administration component appears in DocumentumAdministrator if at least one instance is installed and configured on a repository to which


Administering XML Transformation Services

it is connected. This check is done through executing the DQL/DFC call to find thepresence of at least one cts_instance_info object in the repository.

The following XML Transformation Services administration tasks can be performedthrough Documentum Administrator:• Change your password. Alternatively, this task can be done using the setPassword

utility. Note that the system administrator must also change the password on theserver.

• View log files. Log files are created for each plug-in. The contents and detaillevel of each log file depend on the log file setting you have chosen for the XMLTransformation Services instance.

• View details of an instance. Details include each CTS product that is configured for arepository, the version number of each product, the name of the host machine foreach product, its current status (running or stopped), the time it was last started, thenumber of queued items for the instance, and the number of items processed bythe instance.

• Control a CTS instance. This includes starting, stopping, and refreshing an instance.Note that performing any of these actions will apply to all CTS products runningon the host. This is because all CTS products on a host use the same CTS Windowsservice. Starting and stopping the CTS Windows service can also be done manually,on the host machine. See Starting and stopping XML Transformation Services,page 43.

Starting and stopping the CTS Administration Agent

In order to use the Content Transformation Services Administration component inDocumentum Administrator, it is necessary to have the CTS Admin Agent running onthe CTS host machine. The Admin Agent can be controlled either from the WindowsStart menu or by running a batch file.

To start/stop the CTS Admin Agent through the Start menu:1. Log in to the XML Transformation Services host.


3. Select Documentum CTS Admin Agent.

4. To start the Admin Agent, click Start.To stop the Admin Agent, click Stop.



To start/stop the CTS Admin Agent by running the batch le:1. Log in to the XML Transformation Services host.

2. Navigate to C:\Program Files\Documentum\CTS\Admin Agent\bin.

3. To start the Admin Agent, run the startup.bat file.To stop the Admin Agent, run the shutdown.bat file.

Starting and stopping XML TransformationServices

When you restart the XML Transformation Server host, the XML Transformation Serverwill start automatically. You may also start and stop the XML Transformation Servermanually, using the following procedure. This may be necessary after modifying atransformation profile, for example.

To start/stop XML Transformation Services:1. Log in to the XML Transformation Services host.


3. Select Documentum Content Transformation Services.

4. To start XML Transformation Services, click Start.To stop XML Transformation Services, click Stop.

Note: A background service, called Documentum Content Transformation MonitorServices, restarts XML Transformation Services if it stops unexpectedly. Since themonitor is set to run automatically by default, you will not typically need to accessit. It is located under Windows Services.

Altering timing and operational parametersThe sections that follow explain how to alter the timing and operational parameters thatcan be changed. The following is the basic procedure to follow when changing timingand operational parameters.

To change timing and operational parameters:1. Stop the XML Transformation Server.

2. Change timing and operational parameters as desired.



Refer to the sections that follow for detailed information about options for settingparameters.

3. Restart the XML Transformation Server.

Controlling the logging level

The logging level can be controlled by modifying the log4j.properties file, available in theDocumentum user directory (such as C:\Documentum\config). By default it is set toINFO level. To get more logging information, modify this level to DEBUG.

Note: This task can also be performed through the Content Transformation ServicesAdministration component in Documentum Administrator. See Configuring XMLTransformation Services through Documentum Administrator, page 23.

Managing multiple serversThe standard installation for XML Transformation Services consists of one repositorywith one server. Additional servers can be added to an active repository to enhance itsperformance. Load balancing can optimize performance by spreading transformationrequests between multiple servers.

Load balancing can be achieved by adjusting settings in the CTSServerService.xml file,in the %CTS_HOME%\config folder. By default, CTS products are equipped with astandard load balancing strategy.

The ideal load balancing strategy depends upon your environment and the specificservers in use. Contact your Documentum consulting representative for load balancingguidance.

Changing the CTS Service user after installationIn certain situations, you may need to change the CTS Service user account after XMLTransformation Services has been installed and configured. This may be necessary forsecurity reasons, for example.

It is not necessary to uninstall and reinstall XML Transformation Services to make thischange. Simply ensure that the new user has full COM access permissions for therendering software being used by XML Transformation Services.



Changing the CTS administrator passwordYou can change the CTS administrator’s password by running the setPassword utility.The password also must be changed on Content Server.

To change the administrator’s password:1. Stop Content Transformation Services.

2. Change the password on the Content Server.

3. Open a command prompt window.

4. Enter the following command:> cd %CTS%\docbase\<repository name>\CTSServerScript\bin> setPassword <new_password>

5. Restart Content Transformation Services.

Note: It is also possible to change the password in Documentum Administrator insteadof running the setPassword utility (Step 3 and Step 4 above). You must still performthe other steps in this procedure.

Conguring the queue marker mechanism tomanage queue item sign-off

This procedure applies only if you have different CTS products polling the samerepository but installed on separate hosts.

The queue marker mechanism analyzes queue items and marks those that can beexecuted by the CTS instance, preventing items from being prematurely expired bya CTS instance that cannot handle them.

This functionality is controlled by two elements in the CTSServerService config file:• ignoreItemsToSignOffLimit

This element is used to create the marking job when CTS starts up. If the value is setto "YES", the marker thread will be created. By default, the value is set to "NO", andthere is no marking mechanism.

• markerInterval

This element sets the wait period between consecutive queue marking jobs.The CTSServerService.xml file is located at %CTS_HOME%\config.



The expiration period and marking interval should be tuned based on each systemconfiguration. On a system with similar CTS products polling the same queue, themarker mechanism is not required and thus the default setting is appropriate. However,if there are different CTS products running against a repository, one CTS instance mightexpire items (because it cannot handle them) when the instance that could handle themis busy. In this case, the marking mechanism should be turned on for those instances thatcould process the items.

Working with the CTS Activity Template inDocumentum Process Builder

The CTS Activity Template allows users to add a content transformation as part of aworkflow process. With this version of Advanced Document Transformation Servicesthe CTS Activity Template is available for use with Documentum Process Builder.

Any user profile for Advanced Document Transformation Services can be used with theCTS Activity Template. However, keep in mind that if a profile contains user-definedparameters, these parameters cannot be exposed within the workflow. See Makingtransformation profiles available for use with CTS Activity Template, page 47 for detailsabout choosing profiles and making them available for use with the activity template.

The following section outlines the procedures required to install and use the activitytemplate for Content Transformation Services. It is meant to supplement — not replace— the information in the Documentum Process Builder documentation set. You shouldbe familiar with the Documentum Process Builder application and have access to theDocumentum Process Builder Installation Guide, Documentum Process Builder User Guide, andDocumentum Process Builder Release Notes before proceeding with the tasks in this section.

This section includes the following procedures:

• Making the CTS Activity Template available to users, page 46• Making transformation profiles available for use with CTS Activity Template, page 47• Using the CTS Activity Template, page 48

Making the CTS Activity Template available to users

Users can begin using the CTS Activity Template after:• All installation procedures (as described in XML Transformation Services Installation

Guide) are complete.• The system administrator has given CTS users access to Documentum Process

Builder (consult the Documentum Process Builder User Guide for details).



• The users have set their Preferences to display the CTS palette in DocumentumProcess Builder (see below).

To display the CTS palette in Documentum Process Builder:1. Launch Documentum Process Builder.

2. Select File > Preferences.The Preferences dialog box appears. The list box on the left displays the availableactivity palettes, and the list box on the right displays the palettes currently beingdisplayed in Documentum Process Builder.

Note: Preferences are saved separately for each user. The list of palettes may differ ifyou log in as a different user.

3. To display the CTS palette in Documentum Process Builder, highlight its name inthe left list box and click Add.The name moves to the right list box.

The CTS palette and template are now available to use with a business process.

Note: The preferences you set apply to your user ID only; each user can set differentpreferences.

Making transformation proles available for use withCTS Activity Template

You need to link all CTS Profiles which youwould like to use with CTS Activity Template:

To make transformation proles available for use with CTS ActivityTemplate1. Login to the repository using DAM or WebTop.

2. Navigate to: /System/Media Server/Profiles.

3. Select Show All Object and Versions from the top right hand corner of the screen toview all profiles.

4. Select the required profile from the list.

5. Select Edit>Add to Clipboard from the main menu.

6. Navigate to /System/CTSActvity from the tree menu. Click on the CTSActivityfolder.

7. Select Edit>Link Here from the main menu.



The profile is now linked.

8. Repeat steps 3–7 as required.In Document Transformation Services, only System Profiles are available for CTSActivity Template:

Transformation proles with no parameters

There are profiles that do not include user-defined parameters that are suitable forlinking, for example, transform_to_html_dts. You will find them in the /System/MediaServer/System Profiles folder.

Using the CTS Activity Template

This section describes the CTS Activity Template and the special workflow parametersassociated with it. You will also find the procedure to add a transformation to a businessprocess using the Activity Inspector.

In Documentum Process Builder, activities are the tasks that comprise the workflow.Most of the configuration of the workflow relates to configuring its activities. Youconfigure activities using the Activity Inspector.

The Activity Inspector has several tabs, each corresponding to one aspect of activityconfiguration. When you select the CTS Activity Template, the following tabs areavailable:• The Properties tab sets the priority for automatic activities and lets you provide

instructions for manual performers.• The Performer tab enables you to select who performs the activity and what actions

the performers have available to them.• The Trigger tab settings determine when the activity starts.• The Timers tab sets warning timers to take action if an activity does not start or is not

completed within a designated amount of time.• The Notification tab specifies whether to notify the workflow supervisor when

certain system events occur.• TheDisplay tab controls how the activity appears in the visual display of the process

template.• The CTS Parameters tab enables you to select a transformation and set the options

relating to the transformation.TheDocumentum Process Builder User Guide describes all of these tabs – with the exceptionof the CTS Parameters tab – in the "Working with Activities” chapter. The following



procedure describes how to add a transformation to a business process using the CTSParameters tab in the Activity Inspector.

To add a document transformation to a business process:1. Double click on the CTSActivity node to open the Activity Inspector dialog.

2. Select the CTS Parameters tab.

3. Choose a transformation profile from the Profile Name list box.

4. Select the output format for the transformation from the Target Format list box.

5. Enter a rendition description, if desired.

6. Set this transformation as the default proxy, if desired, by choosing the Yes option.

7. Save this transformation, if desired, by choosing the Yes option.

8. Click Apply to save your updates without closing the Activity Inspector, or click OKto save your updates and close the Activity Inspector.

Consult the Documentum Process Builder User Guide for further instructions on how touse the workflow feature.

To save a new activity template to the repository:1. From the Tools menu, select File > Save.

The Save Process Template dialog appears showing the file structure of therepository.

2. Enter a name for the new activity template in the Name text box.

3. Select Create new folder for associated items, if required.

4. Click OK.The system saves the new workflow template.

5. The Validate Template dialog box appears confirming the workflow has been saved.The dialog box asks if you would like to proceed to validate the template. Click OK.If validation fails, a dialog box appears telling you so. Click the Details button to seethe error that prevented validation. If the validation is successful, a red check markappears next to the activity template icon in the Activity Templates window.

6. The Install Template dialog box appears confirming the workflow has beenvalidated. The dialog box asks if you would like to proceed to install the template tomake it available to all users. Click OK.If the Install option is unavailable, it means the template is currently installed or youdon’t have permission to install. If the installation is successful, an arrow appearsnext to the activity template icon in the Activity Templates window.



7. A dialog box appears to confirm the installation of the template and its activities.Click OK.

To uninstall an activity template:1. From the Tools menu, select Activity Template > Uninstall.

You can only uninstall if the template is in the installed state and you have Writepermission. If the template is successfully uninstalled, the arrow next to the templateicon (representing installed state) is replaced with a red check mark (representingvalidated state).

To start a workow:When you start a workflow, you select the activity template that includes the sequenceof tasks to be performed. and you attach files which are supported by the CTS profileused in the workflow.

See Chapter 6, "Workflows and Quickflows,” in the EMC Documentum Digital AssetManager User Guide for instructions on how to start a workflow.

Using the CTS Reporting ToolThe CTS Reporting Tool provides detailed information about transformation type,volume and error events. Data such as CTS product performance, plug-in usage,and requests by users assists in monitoring and analyzing transformation usage andcan assist with load balancing strategies. Reporting can be logged for a configurabletime frame and then rolled over to be archived. The resulting information is retainedin the repository and is viewable as a CSV formatted file (a report format usingcomma-separated values) through Digital Asset Manager (DAM). Users can view theirown CTS reporting data. Administrators have access to all data.

Usage tracking is configured in Documentum Administrator. The CTS Reporting Toolreports on the number of requests in a given time frame according to the followingoptions:

• Number of successful transformations• Number of requests that could not be handled• Cumulative error report• Number of errors per format and per specific transformation request• Cumulative total file sizes of input and output per given time frame• Total requests per specific user



Enabling and disabling the CTS Reporting Tool

The CTS Reporting Tool is turned off by default. Usage tracking can be switched on oroff.

To enable/disable the CTS Reporting Tool:1. Login to Documentum Administrator.

2. In the tree pane, select Transformation Services>CTS Reporting Configuration

3. Select the following:• Reporting Configuration (ON/OFF) check box, to select whether the data is

collected or not.• Purging Configuration (ON/OFF) option, to delete any data collected.

• Archiving Configuration (ON/OFF) option, to select whether data should bearchived.

4. If you have enabled Reporting Configuration and Archiving Configuration, providethe information for the following fields.• (Number of days) Archiving Interval to set how often the report should be

archived — everyday, every two days, etc.• (Size of transformation request table) Archiving DataSize, to set the number of

transformations that should be recorded at a time before the data is archivedand for the compilation to start again.

• (Archiving monitor interval in seconds) Archiving Monitor Interval, to set the lengthof time in seconds the report should be updated.

5. Click OK.

Viewing the CTS Reporting Tool report

When the CTS Reporting Tool is enabled, the following information is recorded for eachtransformation request:

• The object id of the source document• The object id of the queue item• The user name who sends the requests• The format of the source document SOURCE_FORMAT = "source_format"• The format of target TARGET_FORMAT = "target_format"• The transformation type, it could be either user created or auto/import• The profile name used for the transformation request



• The target object type, it could be rendition or related object• The parameters send in the request• The queue item added time• The queue item signed off time• The transformation completed time• The source file size• The target file size• The status, it could be SUCCESS, FAILED, or UNHANDLED• The CTS instance doing the transformation• Any message resulting from a transformation execution.

To view the CTS Reporting Tool report:1. In DAM, go to Tools>Transformation report>View

2. The CTS Transformation Report page displays. Enter the information for thefollowing fields:• Report name• Start date• End date

3. Click OK.

4. The Select Folder screen appears. Select the destination folder to save the retrievedreport. Click OK. A CSV report opens with the requested information.

Managing the transformation queueThe Queue Management feature provides a mechanism for monitoring andadministrating transformation request queues. This feature allows users to view ordelete their own pending transformation requests. Administrators can manage thequeues for all users and change the priority of transformation requests when required.

The Queue Management feature is accessed through the Transformation node in XMLTransformation Services via Digital Asset Manager (DAM).

Administrators can manage the queue by deleting items or changing the priorityof items. Users can view their own transformation requests and delete their owntransformation requests, but cannot change a queue item priority.

• Viewing transformation requests in the queue, page 53• Changing a queue item’s priority, page 53• Viewing details of a queue item, page 54



• Deleting a pending queue item, page 55• Configuring additional queue management fields, page 55• Removing a queue management field, page 56

Viewing transformation requests in the queue

Users can monitor the status of their transformation requests by viewing the queue. If auser is dissatisfied with the priority level of their transformation request(s), they can asktheir administrator to change an item’s priority on their behalf.

To view transformation requests in the queue:1. Login to DAM.

2. In the tree view on the left side of the screen, select the Transformations node.Click on the Transformations link. The right pane will refresh with a list of currentqueue items.Transformation requests are displayed in priority order. The priority level of an itemis indicated as follows:

• denotes a high priority item

• denotes a medium priority item.

• denotes a low priority item.3. For administrators only: Choose the items to view by selecting an option from

the Show list box in the top right corner:• Show All displays all users transformation requests.• Show Mine displays only your transformation requests.

4. To sort transformation requests in ascending or descending order, click the headerfield on each of the columns.

Changing a queue item’s priority

Administrators can change the priority of an item in the queue.

To change a queue item’s priority:1. Login to DAM.



2. In the tree view in the left pane, select the Transformations node. Go to thetransformation queue by selecting the Transformations node. The transformationqueue appears in the main pane.

3. Find the target item in the queue.

4. Select the item, and right-click with your mouse.

5. Choose View from the context menu.The transformation details of this item are displayed.

6. Change the numeric value in the Priority box. The highest priority is 10. The higherthe numeric value, the higher the priority level. When the priority level is changed,the queue position of the object will change automatically.

7. Click OK. The page returns to the list the transformation queue. Confirm that thequeue position has changed. The color code of the priority item should change toa higher priority. See Viewing transformation requests in the queue, page 53 forqueue item priority level color codes.

Viewing details of a queue item

When a pending item is in the queue, the following transformation details are availabledepending on which fields are configured:• Description gives the name of the transformation being performed, such as Rotate.• Parameters lists any user-defined parameters for this transformation, if applicable.

For a transformation such as Rotate, for example, the angle of rotation would bea parameter.

• From gives the name of the user who requested the transformation.• Received is the date and time the transformation was requested.• Source is the source (or input) file name being transformed.• Priority is given to a queue item with the highest numeric value.• Target is the target (or output) file name for the transformation. If the request is to

create a rendition, the Target field will show "None".• Queue position gives the specific order number of this item in the queue.

To view details of a queue item:1. Login to DAM.

2. In the tree view in the left pane, select the Transformations node. Go to thetransformation queue by selecting the Transformations node. The transformationqueue appears in the main pane.

3. Find the target item in the queue.



4. Select the item, and right-click with your mouse.

5. Choose View from the context menu.The transformation details of this item are displayed.

Deleting a pending queue item

Administrators can delete any items in the queue. Users can only delete their ownqueue items. The deletion is not immediate for users. Items are marked, then polledand then deleted.

To delete a pending queue item:1. Go to the transformation queue by selecting the Transformations node.

The transformation queue appears in the main pane.

2. Find the item(s) to delete from the queue.To find items quickly, you can configure the display as follows:• Sort alphabetically by document name by clicking the header on the Document

column.• Sort the requests alphabetically by user name by clicking the header on the

Sent by column.• Toggle between all users’ transformation requests or your own transformations

using the Show list box.3. Select the item(s), and right-click with your mouse.

Note: You can select a range of items using the Shift key, or select multiple itemsusing the Ctrl key.

4. Choose Delete from the context menu.A delete confirmation page appears for each file you selected.

5. Select OK to confirm a deletion, or click Cancel to abort a deletion request.If the queue item is pending, it will be deleted and removed from the transformationqueue. If the queue item is being processed, an error will show saying "Transformationrequest is being processed, can’t delete."

Conguring additional queue management elds

Users can customize the queue management fields by adding additional columns.



To congure additional queue management elds:1. Login to DAM.

2. Go to the Transformation node.The right pane shows the default column fields.

3. Click on the Column Preferences button.The screen will refresh and show the Preferences: Display Settings on the left andthe default column setting on the right.

4. Select an additional item from the left list "Select attributes to display". Click thebutton to add to the right list "Selected attributes to display as column". The right listshows the new attribute added. Click OK.The list view appears.

5. Verify that the list view has the additional columns.

Removing a queue management eld

Users can customize the column fields by removing select columns.

To remove a queue management eld:1. Login to DAM.

2. Go to the Transformation node.The right pane shows the default column fields.

3. Click on the Column Preferences button.The screen will refresh and show the Preferences: Display Settings on the left andthe default column setting on the right.

4. Select an item from the right list "Selected attributes to display as column". Clickbutton to move it to the left list "Select attributes to display". The right list showsthe new attribute removed. Click OK.The list view appears.

5. Verify that the list view has one less column.



Migrating existing prolesContent Transformation Services migrates existing predefined and custom profiles withminimal modification, from version 5.3 Content Transformation Services productsonwards up to version 6.5, for backward compatibility.

Content Transformation Services performs the following functions during the installationprocess:

• Creates a report summary regarding the changes that are going to happen before theactual migration process starts. The summary report is logged just before the profilemigration tool runs and displays the results.

• Migrates the command line files, profiles, and system profiles to comply withversion 6.5.

Note:

— Legacy profiles that were created using versions of Content TransformationServices products prior to version 5.3 may experience problems duringmigration. In such cases, the profile migration tool migrates the information thatit can and ignores any additional information. If all of the plug-in entries usedin a custom profile are no longer in use, and cannot be updated, the profilewill be deleted.

— Profile names that existed before migration are preserved; however, if multipleinstances of the same profile name exist, the profiles are renamed unlessoverridden by command line options. If a profile is renamed in the currentversion, Content Transformation Services will update the existing profile name.

— If the original name of the profile is too long to be appended, it is shortenedas necessary.

Viewing log le of migrated proles

You can view the log file generated by the profile migration tool. This log file showsthe profiles that were processed, their status, and the reason why if any profiles werenot migrated. The default location of the log file of migrated profiles is C:\ProgramFiles\Documentum\CTS\docbases\<docbase_name>\migration\logfile.

The migration log file shows the result of the migration process:migration_log_2007_292_1192813617312.txt ->Migration log;

The migration report log shows a complete list of all profiles before they are upgraded:migration_report_2007_292_1192813563921.txt ->



Report log

Selecting Internet Protocol versionContent Transformation Services supports Internet Protocol version 6 (IPv6) in dualmode (IPV4 & IPV6). By default, XTS Transformation Services and Content Server areset to both sockets.

Conguring XTS to transform XML contentXML Transformation Services replaces the graphic linked to an XML content with animage of different resolutions according to the required publishing output format. Forexample, you may want a high resolution graphic linked to a PDF rendition and a lowerresolution graphic to an HTML rendition. See Transforming DITA files, page 85 tospecify an resolution type with your document rendition.

Note: This features applies only if XTS is used combination with Media TransformationServices. Media Transformation Services is needed to generate renditions for graphicassets.

Follow this procedure if your XML content (e.g. DITA) requires special processing:

To congure XTS to transform XML content:1. Locate and open the following file %CTS%\config\xpub\xpub.xml

2. Locate the section <PATCHING_CONFIG>

3. From the <PARSE> sub node, select the required attributes:• xpath

Represents an Xpath expression to an XML element that should be parsed.• handler

Represents the type of XML document being processed.• link_type

Rrepresents the type of reference. For DRL patching, values are conref orcrossref; for graphics patching the value is image; for special characters patching,the value is specialchar.



• patcher

Specifies a java class that processes the XML element.• source

Specifies the content origins for which processing should occur. Possible valuesare "repo”, "file”, and "any”.

4. From the <FILE_FILTER> node, select the required attribute:• extension

Lists file extensions of XML content that should be processed.5. Select the <IMG_PATCHING> node if graphics references should be processed. This

is used to map graphics in the original content to a repository rendition that willreplace them. Select the required attributes:• <CONFIG> sub-node:

— target – target format (documentum) of transformation

— handler – type of XML content (see 3-second bullet• <IMAGE_REF > sub-node:

— source_ext

represents the extension of graphic asset file to be replaced

— rend_dctm_format

represents the documentum format of the rendition that should replacethe original file

— rend_flag

specifies the flag value to identify a rendition

— rend_flag_type

Represents the flag type to be checked when used with rend_flag.

Possible rendition attributes are: page_modifier, rendition_name, orrendition_description_name. You can also leave the space empty, in whichcase the first rendition to match the requested format is selected.

6. For DRL Patching, select the <DRL_PATCHING> section. Select the requiredattributes:



• from <PARAM> nodes:

— brokenlink

Specfies a repository location for a dita document that serves as a brokenlink page

— depth

Controls how many levels should be processed when XML files are beingexported as part of processing an existing one.

— special_chars

Lists special characters (separated by ‘/’) that should be replaced with ‘_’in XML file names and references.

7. Restart Content Transformation Services service.


Chapter 4Administering Content TransformationServices Web Services

This chapter contains the following information:

• What are CTS web services, page 61• Web services and Document Foundation Services (DFS), page 63• Content Transformation Services web services architecture , page 64• Asynchronous and synchronous transformation, page 65• Configuring CTS WebServices instance, page 66

What are CTS web servicesDocumentum Content Transformation Services version 6.5 provides two web servicesas an extension of its features for asynchronous and synchronous transformation andanalysis: Profile service and Transformation service. Each service provides a set ofoperations on repository objects and are extended with services that provide additionalplatform functionality.

• Web services are WSDL and Java client library based.• Web services are written to support .NET and Java• Web services are remote or local.• Web services are ready to deploy via J2EE standards (ear and war files).

Prole service

The profile service provides an interface to CTS transformation profiles. The profileservice enables applications to obtain available transformation profiles using variousfiltering mechanisms, as well as to update them if suitable permissions are held by the


Administering Content Transformation Services Web Services

application session. This section describes the operations related to the Profile service.Operations related to Transformation service follow.

For further details about the structure of each operation, such as sample java code andmethods, see EMC Documentum Enterprise Content Services Reference guide.

Operations related to this serviceNote: You need Administrator privileges to perform: addProfile operation;removeProfile operation, and updateProfile operation.

addProfile operation

The addProfile operation adds a CTS profile to the repository from the client wherethe profile is saved.

addProfiles operation

The addProfiles operation adds multiple profiles including command line files, userprofiles, and system profiles to the repository from the client.

getProfileById operation

The getProfileById operation is used to get a specific profile which is queried by itssaved Profile Id.

getProfileByName operation

The getProfileByName operation is used to specify which profile should be invoked toprocess a source object. The profile is queried by the saved profile name and repositorylocation. For example, only the profile with the id "flip” will process the source object

getProfiles operation

The getProfiles operation is used to get an array of profiles which satisfy the query thatspecifies conditions passed with prParam.

removeProfile operation

This removeProfile operation removes a profile with a specific profileId. All versions ofthe profile will be removed, if specified.

updateProfile operation

The updateProfile operation updates a specified saved profile.

Transformation service

The transformation service provides an interface to CTS transformation capabilities. Thetransformation service enables applications to request transformations from the Content



Transformation Services suite of products in both synchronous and asynchronous modes.The following section describes the operations related to the Transformation service.

For further details about the structure of each operation, such as sample java code andmethods, see EMC Documentum Enterprise Content Services Reference guide.

Operations related to this service

addJob operation

The addJob operation creates an asynchronous transformation job in the repositoryand returns a Job Id for tracking purposes.

cleanUpJobs operation

The cleanUpJobs operation deletes all the transformation related objects by a specifieddate.

deleteJob operation

The deleteJob operation deletes only a specific transformation by JobId before it isprocessed. If the job has already started, it will not be deleted

getJobInfo operation

The getJobInfo operation queries the job details of a requested transformation based onthe Job Id. This operation provides the job status about the specified object, for example,getJobInfo will inform if the job is pending, in progress, failed, or complete.

importAndAddJob operation

The importAndAddJob operation submits a transformation request on a source file tothe CTS server asynchronously. The user submits the source file which is imported to therepository from the client’s machine prior to adding it to the queue for transformation

transformJob operation

The transformJob operation submits a transformation request directly to the CTS serversynchronously. The call is made directly to the CTS server and you get the result back.

Web services and Document FoundationServices (DFS)

Document Foundation Services (DFS) delivers a set of core Enterprise Content Serviceswhich are deployed with Content Server where they are hosted by the Java Method



Server. DFS is a multifaceted technology set used for developing and deploying ECMservices and consumers using a service-oriented architecture.

For more information on the DFS, see the Document Foundation Services User Guide.

Content Transformation Services web servicesarchitecture

A CTS web service request involves the exchange of messages amongst three parties:the service provider (server) and requestor (the client) and infrastructure components.Communication between client and server is accomplished through a request/responsemechanism. Service requests and responses are wrapped in XML documents andtransferred using Hypertext Transfer Protocol (HTTP). When the client issues a requestto a service, it goes through a Load Balancer and Web Service Layer. The load balancerdetermines which CTS instance is capable of providing the service for a given request. Itemploys a Java servlet which executes the desired action and sends the results back tothe client. To minimize the required bandwidth between server and client, the servletsperform several actions within the scope of one request and merge the results so that theoperation appears to be just one single action.

Figure 5. Content Transformation Services Web Services Architecture

1. Web services architecture is based on the SOAP protocol. The client sends a requestfor a document transformation invoking the web service. The use of WSDL allowsthe interoperability between services from different sources.

2. The requester relies on the load balancer using a heartbeat mechanism to find theappropriate instance.



• The load balancer is aware of the synchronous supporting CTS instances

• The load balancer loads the profiles from the configured repository into memory

• The load balancer implements the algorithm to determine what instance iscapable of transforming the document. If the request arrives to a failed service, itis redirected to a similar service which is alive.

• The load balancer filters the list of available CTS servers based on product, toservice the request (e.g. MTS registers in the "rotate image” profile).

3. The load balancer matches the request with the service providers to identify which ofthem is the best match. The transform request is sent to the appropriate CTS instance.

4. The transformation occurs.

5. The output file is returned to the client via HTTP or URL.

Asynchronous and synchronoustransformation

There are two ways to call a service, asynchronous and synchronous. The CTS serverprocesses transformation requests from web services and others and transformsaccording to the priority given.

Synchronous requests

The CTS framework is enhanced to support synchronous requests from webservicecomponents in real-time. The real-time architecture’s fair, concurrent thread modelprioritizes CTS tasks to make efficient CTS calls. The synchronous call returns a requestimmediately by bypassing the repository queues through the transformation web servicelayer. A client application requesting real-time transformation may do so accordingto the following content matrix:

• File System Input, Repository Output

Source document is provided from client’s file system and the target output isavailable in the repository.

• File System Input, File System Output

Source document is provided from client’s file system and the target output isavailable in the client machine.



• Repository Input, Repository Output

Source document is provided from the repository and the target output is availablein the repository.

• Repository Input, File System Output

Source document is provided from the repository and the target output is availablein the client machine.

In a ’File System Input, Repository Output’ and ’File System Input, File System Output’real-time web services request, the source file can be either a binary or it can be a urlcontent (a valid URL either a FILE/HTTP protocol) which can be accessible from theCTS server machine.

Failover is only invoked if a process is incomplete or interrupted; otherwise the middletier resubmits the request to another running instance that can handle it.

CTS asynchronous architecture

An asynchronous request interacts with DFC, which in turn interacts with ContentServer to generate transformation queue items. An asynchronous request leverages CTSarchitecture. The CTS instance polls the queue item and performs the transformation.The result is stored in the repository.

Conguring CTS WebServices instanceThis section contains the following information:

• Configuring CTS WebServices instance for JBoss, page 66• Configuring CTS WebServices instance for other supported applications, page 69

Conguring CTS WebServices instance for JBoss

The CTS WebServices installer installs all the necessary files to run and configure thecore components of CTS web services. Follow these steps to configure CTS WebServicesinstance to a JBoss application server. To configure CTS WebServices for other supportedenvironments, go to Configuring CTS WebServices instance for other supportedapplications, page 69.



To congure CTS web services instance:1. From the main menu, select Start>Documentum>CTS WebServices Configurator.

The installation wizard appears.

2. Click Next on the Welcome screen.

3. Accept the licence agreement on the Licence screen and click Next.

4. Select Add a CTS Web Services instance to a docbase radio button and click Next.This is the only option displayed if this is the first time the CTS WebServices configuratoris invoked.

5. Verify the hostname fetched by the configurator. Provide the domain name ifrequired. Click Next.

6. Select the docbase from the list of docbases retrieved by default. Retrieving docbasesdepends on the docbroker IP’s provided in dfc.properties.

7. Enter your super username and password. Click Next.

8. Click Finish to complete the configuration process.

Verifying conguration of CTS web services

By default CTS web services instance (JBoss application server) runs on port 8888.

To verify conguration of CTS web services instance:Open the http://localhost:8888 from CTS web services machine to check to see if theJBoss console is open.

Verifying CTS web service le are accessible

Enter the following URLs to check if all WSDL files are accessible:

From CTS web services machine

• ObjectService:

http://localhost:8888/services/core/ObjectService• ProfileService

http://localhost:8888/services/transformation/ProfileService• TransformationService:

http://localhost:8888/services/transformation/TransformationService



From a remote machine (client machine)

• ObjectService:

http://:<CTSWS_HOST IP>:8888/services/core/ObjectService>• ProfileService

http://:<CTSWS_HOST IP>:8888/services/transformation/ProfileService• TransformationService:

http://:<CTSWS_HOST IP>:8888/services/transformation/TransformationService

Verifying deployment of EAR les

CTS WebServices installer deploys emc-dfs.ear and transformation.ear files at:C:\Documentum\jboss4.2.0\server\DctmServer_DFS-CTS\deploy folder.

The ear files are exploded and the folder should be labelled dfs.ear and transformation.earrespectively.

Verifying contents of transformation.properties le

Open the transformation.properties file at: "C:\Documentum\jboss4.2.0\server\DctmServer_DFS-CTS\conf" folder. The CTSWSConfig file should point to thecorrect preferences.xml file location used by the CTS WebServices configurator:CTSWSConfig=C:/Documentum/cts_ws/config/preferences.xml

Verifying preferences.xml le is updated with congured repository

Ensure the preferences.xml file is available at the %CTS_HOME%\config folder. Thisfile holds data required for Transformation Services such as: repository name, username,domain name and password, and file location. The configurator updates the elements ofthis file.

A password file (with encrypted password) is created and placed in%CTS_HOME%\config\pfile folder.<Repositories><AekFilePath>C:/Documentum/cts_ws/config/aek.key</AekFilePath><LoginContect DocbaseName-"DTS_Repo"><ServerProperty Key-"domain"Value-""/><ServerProperty Key-"userName" Value-"documentum"/><ServerProperty Key-"passwordFile"Value"-"C:/DOCUME~2/cts_ws/config/pfile/DTS-Repo_password.txt"/>



<ServerProperty Key-"maxConnectionRetries" Value-"10"/></LoginContext"</Repositories>

Location of realtime requests log les

The CTS WebServices log files are located at : C\Documentum\cts_ws\logs. The log fileis created once the first request is serviced from the client.

Conguring CTS WebServices instance for othersupported applications

To deploy CTS webservices on a supported application server other than JBoss, completethe following steps. (See Advanced Document Transformation Services Release Notes for alist of supported environments.)

To congure CTS WebServices instance for other supported applications:1. Deploy emc-dfs.ear file by copying it to the deploy directory of your supported

application server instance. See Chapter 4,"Manually deploying services onsupported application servers,” in the EMC Documentum Documentum FoundationServices Deployment Guide Version 6.5 for complete instructions.

2. Deploy transformation.ear file by copying it to the deploy directory of yoursupported application server instance. See Chapter 4,"Manually deploying serviceson supported application servers,” in the EMCDocumentumDocumentum FoundationServices Deployment Guide Version 6.5 for complete instructions.

3. Start the Windows service for the server instance.Restart the app server for applications other than Windows.

4. Enter the following URLs to check the accessibility of WSDL files:From CTS webservice machine:• ObjectService:

http://localhost:port/services/core/ObjectService?wsdl• ProfileService

http://host:port/services/transformation/ProfileService?wsdl• TransformationService:

http://host:port/services/transformation/TransformationService?wsdl5. On CTS web services machine, at your working directory, create a "cts_ws” folder.



6. Create and add the following subfolders to the "cts_ws” folder.• \cache• \config• \pfile• \logsThe following paths are created:• %CTS_HOME%\cts_ws\cache• %CTS_HOME%\cts_ws\config• %CTS_HOME%\cts_ws\logs• %CTS_HOME%\cts_ws\config\pfile

7. Open your text editor and create a preferences.xml file with the following content:

Note: You will need the following information:

• File path• Docbase name• Domain name• User name

<?xml version="1.0" encoding="UTF-8"?><ServiceConfiguration ID="CTS Web Services"><PropertyList><ServerProperty Key="Cache" Description="The Temperory

Cache Directory" Value="C:\Documentum\cts_ws\cache" /><ServerProperty Key="AllowDirectTransfer" Description=

"Allow Direct File Transfer From CTS Server to Client.Set it to false if there is a firewall restriction" Value="true" />

<ServerProperty Key="CTSWSPingInterval" Description="Interval(in seconds) used to specify how frequent the LB should ping itsCTS instances for heart rate." Value="180" />

<ServerProperty Key="FailoverRetries" Description="Allow anumber of retries if a request fails while waiting on the HTTPresponse from CTS" Value="1" />

<ServerProperty Key="InstanceSelector" Description="Specifyan implementation class for instance selection " Value="com.emc.documentum.cts.lb.workers.DefaultSelector"/>

<Repositories><AekFilePath>C:\Documentum\cts_ws\config\aek.key/

<AekFilePath><LoginContext DocbaseName="docbase_name_here"><ServerProperty Key="domain" Value="domain_name_here"/><ServerProperty Key="userName" Value="user_name_here"/><ServerProperty Key="passwordFile" Value="C:\Documentum\

cts_ws\config\pfile\mspassword.txt"/><ServerProperty Key="maxConnectionRetries" Value="10"/></LoginContext></Repositories>

</PropertyList></ServiceConfiguration>



8. Place the preferences.xml file in the config folder.The preference file holds data required for Transformation services, such as:repository name, username, domain name and password, and file location. Theconfigurator job updates the elements of this file.

9. Copy the aek.key file from %CTS_HOME%\config from the CTS Server machine to%CTS_HOME%\cts_ws\config on the CTS WebServices machine.

10. Copy the mspassword.txt from: C:\ProgramFiles\Documentum\CTS\docbases\docbase_name\config\pfilefrom the CTS machine to C:\Documentum\cts_ws\config\pfile on the CTSwebservice machine.

11. Copy the transformation.properties file from \transformation.ear\APP-INF\classesto the application server’s current working folder. (See Locating working folder ifyou cannot locate the current working folder.)

12. Open the transformation.properties file at %CTS_HOME%\config folder and edit topoint to the preferences.xml file:

CTSWSConfig=C:/Documentum/cts_ws/config/preferences.xml

13. Edit the log4j.properties file located under \transformation.ear\APP-INF\classes tocreate logs under %CTS_HOME%\config\cts_ws\logs folder.

- FILE -log4j.appender.F1=org.apache.log4j.RollingFileAppender

log4j.appender.F1.File=C\:/Documentum/cts_ws/logs/log4j.log

log4j.appender.F1.MaxFileSize=10MB

log4j.appender.F1.layout=org.apache.log4j.PatternLayout

log4j.appender.F1.layout.ConversionPattern=%d{ABSOLUTE} %5p[%t] %-20c{1} - %m%n

- FILE_TRACE -log4j.appender.FILE_TRACE=org.apache.log4j.RollingFileAppender

log4j.appender.FILE_TRACE.File=C\:/Documentum/cts_ws/logs/trace.log

log4j.appender.FILE_TRACE.MaxFileSize=100MB

log4j.appender.FILE_TRACE.layout=org.apache.log4j.PatternLayout

log4j.appender.FILE_TRACE.layout.ConversionPattern=%d{ABSOLUTE}[%t] %-20c{1} - %m%n

- CTSWS -log4j.category.com.emc.documentum.fs.services.transformation=DEBUG,CTSWSAppender



log4j.category.com.emc.documentum.cts=DEBUG, CTSWSAppender

log4j.appender.CTSWSAppender=org.apache.log4j.DailyRollingFileAppender

log4j.appender.CTSWSAppender.File=C\:/Documentum/cts_ws/logs/CTSWS_log.txt

log4j.appender.CTSWSAppender.Append=true

log4j.appender.CTSWSAppender.layout=org.apache.log4j.PatternLayout

log4j.appender.CTSWSAppender.layout.ConversionPattern=%d{HH\:mm\:ss,SSS} %5p %-20c{1} %m%n

log4j.appender.CTSWSAppender.DatePattern='.'yyyy-MM-dd

- DFS-log4j.category.com.emc.documentum.fs=INFO, DFSAppender

log4j.appender.DFSAppender=org.apache.log4j.DailyRollingFileAppender

log4j.appender.DFSAppender.File=C\:/Documentum/cts_ws/logs/DFS_log.txt

log4j.appender.DFSAppender.Append=true

log4j.appender.DFSAppender.layout=org.apache.log4j.PatternLayout

log4j.appender.DFSAppender.layout.ConversionPattern=%d{HH\:mm\:ss,SSS} %5p [%t] %-20c{1} - %5x %m%n

log4j.appender.DFSAppender.DatePattern='.'yyyy-MM-dd

14. Restart the webservice application server.

Locating CTS WebServices log le

The CTS WebServices log files are located at %CTS_HOME%\cts_ws\logs. The log file iscreated once the first request is serviced from the client.


Chapter 5Working with Proles

The predefined profiles in XML Transformation Services cover most of the common documenttransformations, such as XML to PDF and XML to HTML. XML Transformation Services enables thesystem administrator to modify existing profiles or create new profiles.

You can modify a system profile if the current profile is unsuitable for your needs. Modifying aprofile will customize it to your specifications.

Understanding command-line lesCommand-line files are stored in the repository as XML files that can be used by thetransformation profiles as needed.

The command-line file contains detailed instructions for the plug-in. The XMLTransformation Server distinguishes between DITA and DocBook source filesthrough the input_doctype_family name token in the plug-in configuration file. Thecommand-line file may also contain additional parameters that are not user-selectable,such as stylesheet associations. The resulting file format and many of its attributes couldbe 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 clientapplication), a description, required attributes, and supported source/target dm_formatobjects. Profiles for which all parameters are defined contain only the name, label,description, and supported source and target formats. Each profile is linked to eitherthe DITA or DocBook command-line file.


Working with Proles

Building and modifying proles with ProleEditor

The Profile Editor assists with editing or building new profiles. New or existing profilescan be customized by editing default values and adding or removing formats. Users canselect multiple profiles to create chained or parallel profiles that automate a series oftransformations. Both user and system profiles can be handled with the Profile Editor.You can also add or remove profiles, to and from the original selection, rearrange theorder of profiles, and configure the desired behavior for a profile with the Profile Editor.

Note: Multi-language support is not available with Profile Editor for Version 6.5. SeeXML Transformation Services Release Notes for further information.

This section contains the following procedures:

• Editing a profile, page 74• Building a new profile, page 75• Building a chain profile, page 77• Building a parallel profile, page 79The following procedure describes how to edit a profile in a repository using the ProfileEditor

Editing a prole

The following procedure describes how to edit a profile to update or customize it.

To edit a prole:1. Log in to Digital Asset Manager (DAM) as the Administrator.

2. From the DAM browser tree, select Administration>CTS>Profiles node.

3. The list of public profiles appears by default (Show public). In the drop down menu,in the top right hand corner of the pane, select Show public and system to changethe view to all profiles. A list of profiles appears.

4. Select a profile from the list that you would like to update.

5. Select Tools>Edit Profile (or select the profile, right-click, and select Edit).The Info tab displays.

6. On the Info tab, edit the name, label, and description of the profile, if required.• ClickWebtop Enabled, if required.• Click Browse to edit the folder destination, if required.


Working with Proles

• Click System if you wish to hide the profile, if required.Click Next. The Formats tab displays.

7. The Formats tab contains all the formats supported by XML Transformation Servicesto generate default renditions for that profile.Select the profile’s new source and target format from the list provided.• If required, click Add to include additional source and target formats from the

Format Selector.• Select new source and target from the Source Format and Target Format list

boxes. Click OK.• To remove a format from the Formats tab, click Remove. Click OK.Click Next. The Parameters tab appears listing the available parameters for theedited profile.

8. Select the parameter(s) desired.• Click Configure, to configure the profile parameter, if required.• Enter the field values. Click OK. The Parameters tab refreshes.• Select the edited parameter.Click Next. The Summary screen appears.

9. The Summary screen confirms the elements that were selected and defined in theprevious screens.Click Finish to validate and save the new profile.

10. The Profiles page is displayed. Verify that the edited profile appears on the Profilespage.

11. All profile changes require that you stop and restart the Content TransformationServices service (see Starting and stopping XML Transformation Services, page 43)on the XML Transformation Services host.

Building a new prole

The following procedure describes how to build a new profile using an existing profile.

To build a new prole:1. Log in to Digital Asset Manager (DAM) as the Administrator.




Working with Proles

4. From the list, select the existing profile with which you will build the new profile.Select Tools>Build Profile.The Info tab will display.

5. On the Info tab, edit the name, label, and description of the profile, if required.• ClickWebtop Enabled, if required.• Click Browse to edit the folder destination, if required.• Click System if you wish to hide the profile, if required.Click Next. The Formats tab appears.

6. The Formats tab contains all the formats supported by XML Transformation Servicesto generate default renditions for that profile.Select the profile’s new source and target format from the list provided.• If required, click Add to include additional source and target formats from the

Format Selector.• Select new source and targets from the Source Format and Target Format list

boxes. Click OK.• To remove a format from the Formats tab, click Remove. Click OK.Click Next. The Parameters tab appears.

7. The Parameters tab lists the available parameters for the edited profile. Select theparameter(s) desired.• Click Configure, to configure the profile parameter, if required.• Enter the field values.• Click OK. The Parameters tab refreshes.• Select the adjusted parameter.Click Next. The Summary screen appears.

8. The Summary screen confirms the elements that were selected and defined in theprevious screens.Click Finish to validate and save the new profile.

9. The Profiles page is displayed. Verify that the new profile appears on the Profilespage.



Working with Proles

Building a chain prole

Chaining profiles invoke each profile within them in stages. Transformations also occurone at a time, one transformation is required for the next transformation. The result of achaining profile would be the output of the last profile in the chain. A chained profilecreates one output file.

The following procedure describes how to create a chained transformation according toyour specific requirements.

To build a chain prole:1. Log in to Digital Asset Manager (DAM) as the Administrator.



4. From the list, select the profiles with which you will build the new profile. SelectTools>Build Profile>Chain.

5. The Info tab will display.• Enter the generic name, label, and description of the new profile.• ClickWebtop Enabled, if required.• Click Browse to edit the folder destination, if required.• Click System if you wish to hide the profile, if required.Click Next. The Inner Profiles — Selection tab displays.

6. The Inner Profile — Selection pane will display. This tab allows users to add,remove, rearrange the desired inner profiles.• Select the inner profile(s) that you require from the Available Profiles drop down

list. Use the directional arrow, to move the selection(s) to the Selected Profileslist box. The right list shows the new product(s) added. OR

• Select the inner profile(s) from the Selected Profiles list. Use the directionalarrow, to move the selection(s) to the Available Profiles lists. The right list showsthe new product(s) added.

• Use the up and down directional arrow to rearrange the Selected Profiles list tocreate the desired sequence in the chain profile.

Click Next. The Inner Profile — Details pane displays.

7. The Inner Profile — Details pane details the profiles selected for the chain profile. Toconfigure a path:• Select a path


Working with Proles

• Select Configure to configure an inner profile path, if required.• Select the desired output format from the list box.• Wait on completion is disabled for chained profiles.• Click OK.• Repeat Step 7 for each path you would like to configure.Click Next. The Formats tab displays.

8. The Formats tab contains all the formats supported by XML Transformation Servicesto generate default renditions for that profile. Select the profile’s new source andtarget format from the list provided.• click Add to edit the format, if required. The Format Selector screen appears.• Select an additional source and target pair from the Source Format and Target

Format list boxes.• Click OK. The Formats Page displays.• To remove a format from the Formats tab, select the Source and Target pair,

and click Remove.Click Next. The Parameters tab appears. listing the available parameters for thechain profile.

9. The Parameters tab appears lists the available parameters for the chain profile.• To configure a parameter, select the profile and parameter label.• Click Configure. The Configure pane displays.• Click Default Settings to select default values from the Default Values list box.• Select Hidden to hide the profile.• Click OK. The Parameter tab refreshes with the new information.• Repeat Step 9 until you have configured all the profile paths that you require.Click Next.

10. The Summary page is displayed. This screen confirms the elements of the chainedprofile.Click Finish to validate and save the new profile.




Working with Proles

Building a parallel prole

The following procedure describes how to create a parallel transformation according toyour specific requirements.

Parallel profiles specify a list of profiles that are executed one after another or at the sametime. For each profile in the parallel profile, you can specify whether the next profileshould wait on the successful completion of the previous task. If there is no specification,profiles can be executed as soon the tasks threads are available to process them. Eachprofile does not have to be complete before the next profile starts. The result of parallelprofiles is one output file for each profile within the parallel profile.

To build a parallel prole:1. Log in to Digital Asset Manager (DAM) as the Administrator.



4. From the list, select the profiles with which you will build the new profile. SelectTools>Build Profile>Parallel.The Info tab will display.• Enter the generic name, label, and description of the new profile.• ClickWebtop Enabled, if required.• Click Browse to edit the folder destination, if required.• Click System if you wish to hide the profile, if required.Click Next. The Inner Profiles — Selection tab displays.

5. The Inner Profile — Selection pane will display. This tab allows users to add,remove, rearrange the desired inner profiles.• Select the inner profile(s) that you require from the Available Profiles drop down

list. Use the directional arrow, to move the selection(s) to the Selected Profileslist box. The right list shows the new product(s) added. OR

• Select the inner profile(s) from the Selected Profiles list. Use the directionalarrow, to move the selection(s) to the Available Profiles lists. The right list showsthe new product(s) added.

• Use the up and down directional arrow to rearrange the Selected Profiles list tocreate the desired sequence in the chain profile.

Click Next. The Inner Profile — Details pane displays.

6. The Inner Profile — Details pane details the profiles selected for the parallel profile.To configure a path:


Working with Proles

• Select a path• Select Configure to configure an inner profile path, if required.• Select the desired output format from the list box.• Click OK.• Repeat for each path you would like to configure.Click Next. The Formats tab displays.

7. The Formats tab contains all the formats supported by XML Transformation Servicesto generate default renditions for that profile. Select the profile’s new source andtarget format from the list provided.• click Add to edit the format, if required. The Format Selector screen appears.• Select an additional source and target pair from the Source Format and Target

Format list boxes.• Click OK. The Formats Page displays.• To remove a format from the Formats tab, select the Source and Target pair,

and click Remove.Click Next. The Parameters tab appears. listing the available parameters for thechain profile.

8. The Parameters tab appears lists the available parameters for the chain profile.• To configure a parameter, select the profile and parameter label.• Click Configure. The Configure pane displays.• Click Default Settings to select default values from the Default Values list box.• Select Hidden to hide the profile.• Click OK. The Parameter tab refreshes with the new information.• Repeat step 8 until you have configured all the profile paths that you require.Click Next.

9. The Summary page is displayed. This screen confirms the elements of the parallelprofile.Click Finish to validate and save the new profile.




Working with Proles

Modifying proles manuallyThis section describes how to modify a system profile manually. You can modify aprofile if the current profile is unsuitable for your needs. Modifying a profile willcustomize it to your specifications.

XML Transformation Server updates all dm_media_profile objects on startup. It removesall repeating SOURCE and TARGET attributes and resets them. Therefore, when a usermodifies a dm_media_profile object, XML Transformation Server automatically updatesthe object when the server restarts.

The following procedure describes how to modify a profile in a repository.

To modify a transformation prole:1. Log in to the repository using an appropriate application (such as Webtop or Digital

Asset Manager).

2. Navigate to /System/Media Server/System Profiles.

3. Check out and edit the profile you want to modify.



5. If the profile was part of a chain or sequence, then you must stop and restartthe Content Transformation Services service (see Starting and stopping XMLTransformation Services, page 43) on the XML Transformation Services host.

Using DQL in prolesDocument Query Language (DQL) can be specified for all XML Transformation Servicesprofile files. Through DQL, default profile parameters can be supplied.

The DQL is presented as an attribute of the Parameter node of profiles (named dql). Thissection discusses:

• The dql attribute value syntax, page 82• DQL guidelines, page 82• DQL query examples, page 82• Querying the r_object_id attribute, page 83


Working with Proles

The dql attribute value syntax

The syntax for the dql profile parameter attribute value does not differ from a regularDQL statement. It supports the following tokens (placeholders) which are recognizedby the system:

• [sysobject_id_token]: placeholder for a Sys Object ID (the r_object_id attribute fordm_sysobject)

• [format_token]: placeholder for the rendition’s format (string)• [page_token]: placeholder for the page attribute of dmr_content (integer)• [page_modifier_token]: placeholder for the page_modifier attribute of dmr_content

(string)These tokens are replaced at runtime with the actual values taken from the source sysobject that is used to execute the profile, before executing the actual query.

DQL guidelines

Consider the following guidelines when supplying DQL for profiles:

• The system does not try to correct a wrong query. It always assumes the query iscorrectly supplied in profile. The system replaces the contained placeholders withruntime values, and then executes it against the repository.

• Upon executing the query, the system will just consider the first row returned inthe result set. If the query is set to return multiple records, just the first one willbe considered.

• All the attribute values returned will be formatted accordingly, based on the attributetype (such as date, string, or Boolean).

DQL query examples

Complex queries can be created with DQL. Queries can include all four supportedtokens, as many times as they are needed. The following examples illustrate how tosupply the DQL for the dql profile parameter attribute:<Parameter name=”doc_token_text” label=”New Text” controltype=”text”datatype=”string” dql=”SELECT OBJECT_NAME FROM dm_document WHEREr_object_id = [sysobject_id_token]”><Value label=”text”/></Parameter>

<Parameter name=”doc_token_text” label=”New Text” controltype=”text”datatype=”string” dql=”SELECT 'NAME:' as label, object_NAME FROM


Working with Proles

dm_document WHERE r_object_id = [sysobject_id_token]”><Value label=”text”/></Parameter>

<Parameter name=”doc_token_text” label=”New Text” controltype=”text”datatype=”string” dql=”SELECT 'Modified:' as label, r_modify_date FROMdm_document WHERE r_object_id = [sysobject_id_token]”><Value label=”text”/></Parameter>

The following query can be used to get the current lifecycle state for a sys object, as string:<Parameter name=”doc_token_text” label=”New Text” controltype=”text”datatype=”string” dql=”SELECT state_NAME FROM dm_policy a, dm_sysobject bWHERE a.r_object_id = b.r_policy_id AND a.i_state_no = b.r_current_stateAND b.r_object_id = [sysobject_id_token] ENABLE(row_based)”><Value label=”text”/></Parameter>

To get information that is pertinent to the user who executes the profile, the userkeyword can be used in query:<Parameter name=”doc_token_text” label=”New Text” controltype=”text”datatype=”string” dql=”SELECT user_NAME, user_address FROM dm_userWHERE user_NAME = USER”><Value label=”text”/></Parameter>

Querying the r_object_id attribute

Having the r_object_id attribute as part of the SELECT clause of the query will not resultin having the actual Object ID value supplied as part of the default parameter value. Thisattribute sometimes has a special (system) role in query (for example, properly returningthe repeating attributes in a single row). The system cannot process its real purpose atruntime, and therefore will not consider it when building the profile parameter defaultvalue.

To have the Object ID value supplied as part of the profile default parameter value,syntax must be provided touse the [sysobject_id_token] placeholder on the query’sSELECT clause, as follows:<Parameter name=”doc_token_text” label=”New Text” controltype=”text”datatype=”string” dql=”SELECT [sysobject_id_token] as objectid FROMdm_document WHERE r_object_id = [sysobject_id_token]”><Value label=”text”/>


Working with Proles

</Parameter>


Chapter 6Performing Transformations

XML Transformation Services offers various transformation options to users. This chapter providesbasic procedural information for performing these transformations.

As with all Content Transformation Services products, the capabilities of XML TransformationServices are accessed through Digital Asset Manager, a Documentum client application. To performthese transformations, log in to the repository serviced by XML Transformation Services.

The user transformations available with XML Transformation Services are explained in the followingsections:• Transforming DITA files, page 85• Transforming DocBook files, page 87• Viewing renditions, page 92Transformations that create new renditions occur on one item at a time and requests are processedasynchronously, meaning that new renditions may not be available immediately. You receive anotification in your Inbox when a transformation is completed or if a transformation fails. Viewingrenditions, page 92 describes where to find and how to view completed transformation requests.

Note: The transformation options presented to the user depend on the type of source documentchosen for transformation. For example, if a DITA source file is selected, DocBook profiles are notavailable.

Transforming DITA lesTransformation of DITA compliant XML files to PDF, HTM, ZIP, EclipseHelp, JavaHelp,RTF, or DocBook are handled by one profile. Users select the output format and contentfilters for each transformation.

To transform a DITA source le:1. Navigate to the file that you want to transform to create a new rendition.

2. Select the file, then select Tools > Transform > More Formats


Performing Transformations

The Select Transformation tab appears displaying the selected file and the availabletransformations for the selected file.

3. Select Transform DITA. Click Next.The Transformation Details tab appears.

4. Perform the following selections:• Select the output format for the transformation from the Format Output listbox.• Choose the filter parameters you wish to exclude in he Operating System Filter

box, i.e. select all of the operating systems that do not apply. The OperatingSystem Filter box lists filters that have likely been customized by yourorganization and will vary according to your organization’s requirements.

Note: For all DITA transformations, you choose the filter parameters you wish toexclude. For example, to filter the content based on operating systems, select allof the operating systems that do not apply.

• Select the document version types from the Revision Filter listbox that youwish to exclude.

• Select the audience level filter from the Audience Filter listbox that you wish toexclude.

• Enter a product filter type in the Product Filter field box, if required.• Select No in the Zip multiple-file listbox, if you do not wish to have the a

multiple file output zipped.

The default value is Yes. This parameter only applies when creating a NewObject.

• Select Yes in the Change graphics resolution listbox, if you need to have theXML content processed for graphics replacement. The default value is No.

• Click Next. The Save As screen appears.5. Select one of the following:

• Create a New Rendition, or• Create a New Object

Selecting Create a New Object will allow you to use this object in its ownworkflow, create a translation of it, apply its own permission, etc.

6. If you selected Create a New Rendition, the Rendition Definition screen appears.Enter a description of the rendition in the Rendition Description field.• Click Save Transformation if you wish to perform this transformation every time

the parent object is versioned.• Click Set As Default Preview, if you wish to set this rendition as the default

preview rendition.

Note: A format must be richmedia_enabled to allow for transformation whenever itis versioned.



Click Finish.

7. If you selectedCreate a NewObject, the NewObject Definition screen appears. Entera title of the new object in the Title field. Perform any of the following as required:• Select the object type from the Object Type list box.• Click Edit next to Permission Set if you wish to change permission parameters.

Click OK.• Click Edit next to Lifecycle if you wish to change document lifecycle information.

Click OK.• Click New Location option to change and log the new file location. Click OK.• Click Save Transformation if you wish to apply this transformation every time

the parent object is versioned.


Click Finish

8. The transformation request is immediately sent to the appropriate queue forprocessing.

Transforming DocBook lesThere are three profiles available for transforming DocBook source files. Each profiletransforms the XML source into a different output format.

This section describes how to transform DocBook source files to:• Compiled HTML Help output (CHM)• HTML output• PDF output

Transforming DocBook les to CHM

This profile transforms Docbook compliant files to Microsoft HTML Help (CHM). Userscan choose parameters relating to the CHM output, including certain table of contents(TOC) parameters.

To transform a DocBook source le to CHM output:1. Navigate to the file that you want to transform to create a new rendition.

2. Select the file, then select Tools > Transform > More Formats



The Select Transformation tab appears displaying the selected file and the availabletransformations for the selected file.

3. Select DocBook to CHM. Click Next.The Transformation Details tab appears.

4. Perform the following selections: Select one of the options from the Set DraftWatermark• Select one of the options from the Set Draft Watermark listbox.• Select the display parameter from the Display Comments listbox.• Select the desired chunking depth level from the Create New HTML Files Down

to Section Level list box.• Select the desired chunking depth level from the HTML Help TOC Section

Depth list box.• Select Yes or No from the Display Chapter (and Section) Numbers in HTML

Help TOC list box.• Choose the appropriate filters for this transformation in the Operating System

Filter box. The filters that appear have likely been customized by yourorganization, and will vary according to your organization’s requirements.

• Select the required level in the Audience Filter box.• Select the version level of the file in the Revision Filter box.• Fill in the Product Filter field, if required.

5. Click Next. The Save As screen appears.

6. Select one of the following:• Create a New Rendition• Create a New Object

Selecting Create a New Object will allow you to use this object in its ownworkflow, create a translation of it, apply its own permission, and so on.



preview rendition.


Click Finish.

8. If you selectedCreate a NewObject, the NewObject Definition screen appears. Entera title of the new object in the Title field. Perform any of the following as required:



• Select the object type from the Object Type list box.• Click Edit next to Permission Set if you wish to change permission parameters.


Click OK.• Click New Location to change and log the new file location. Click OK.• Click Save Transformation if you wish to apply this transformation every time



Click Finish


Transforming DocBook les to HTML

Users can select from a variety of options for customizing HTML output, includingthe chunking depth.

To transform a DocBook source le to HTML:1. Navigate to the file that you want to transform to create a new rendition.

2. Select the file, then select Tools > Transform > More FormatsThe Select Transformation tab appears displaying the selected file and the availabletransformations for the selected file.

3. Select DocBook HTML Transform option. Click Next.The Transformation Details tab appears.

4. Enable the following options as appropriate:• Set Draft Watermark• Display Comments• Create New HTML Files Down to Section Level (which determines the

chunking depth)5. Choose the appropriate filters for this transformation. The filters that appear have

likely been customized by your organization, and will vary according to yourorganization’s requirements.



Note: For all DITA transformations, you choose the filter parameters you wish toexclude. For example, to filter the content based on operating systems, select all ofthe operating systems that do not apply.

Click Next. The Save As screen appears.





preview rendition.


Click Finish.






Click Finish




Transforming DocBook les to PDF

Users can customize the output PDF by choosing from various output options such aspaper type and page orientation.

To transform a DocBook source le to PDF:1. Navigate to the file that you want to transform to create a new rendition.

2. Select the file, then select Tools > Transform > More FormatsThe Select Transformation tab appears displaying the selected file and the availabletransformations for the selected file.

3. Select Transform DocBook to PDF option. Click Next.The Transformation Details tab appears.

4. Enable the following options as appropriate:• Set Draft Watermark• Display Comments• Paper Type• Render for Double-Sided Printing• Page Orientation

5. Choose the appropriate filters for this transformation. The filters that appear havelikely been customized by your organization, and will vary according to yourorganization’s requirements.

Note: For all DITA transformations, you choose the filter parameters you wish toexclude. For example, to filter the content based on operating systems, select all ofthe operating systems that do not apply.

Click Next. The Save As screen appears.





preview rendition.




Click Finish.






Click Finish


Viewing renditionsWhen transformation requests are completed, the renditions are stored in the repositorywith the source file.

To view completed transformation requests:1. Navigate to the source file in the repository.

2. To view renditions in Digital Asset Manager, click the renditions icon.To view renditions in Webtop, select the source file. Then click View > Renditions.

Note: Do not select Download Descendants when viewing renditions. An errorwill occur.


Chapter 7Troubleshooting

This chapter provides troubleshooting information for errors encountered from various elementsof XML Transformation Services. Also see XML Transformation Services Release Notes, which containadditional information regarding limitations, technical notes, usability, and known bugs.

This section contains troubleshooting guidance relating to:• Error events and log files, page 93• A transformation request fails, page 94• A profile error occurs, page 94• XML Transformation Server cannot add a rendition to a particular format, page 95• XML Transformation Server cannot log in to the repository, page 95• CTS Administration Agent gives AGENT_INACCESSIBLE message, page 96• Content Transformation Services fails to function, page 97• Locating application server working folder, page 97

Error events and log lesAny time XML Transformation Server fails to process a particular item, it queues anevent (dm_autorender_error or dm_mediaserver_error) to the Inbox of the repositoryuser defined as the system operator in the XML Transformation Server configurationfile. The first step in troubleshooting XML Transformation Server is to check the systemoperator’s Inbox for any messages that might explain the error.

Additionally, review the CTS_log.txt log file. This log file contains errors and exceptionsthat are specific to XML Transformation Server. It is located on the XML TransformationServer host, in this directory:C:\Program Files\Documentum\CTS\config\logs


Troubleshooting

A transformation request failsOccasionally, a transformation request may fail to process, or may process incorrectly. Inmost cases, the error messages will indicate the problem.

Notification of a transformation failure will be sent to the system operator’s Inbox. Thefollowing actions can be performed to determine the cause of a transformation requestfailure.

To troubleshoot the failure of a transformation request:1. Check that the object of the transformation request is not locked (checked out of the

repository). If the object is locked during the transformation, the operation fails.

2. Check for error messages in the system operator’s Inbox, indicating that the formatof the file being transformed does not adhere to system specifications. For example,the file may be corrupted, or compression or other similar features of the file maynot be supported by XML Transformation Services.

3. Check that disk space and memory on the XML Transformation Server host issufficient to handle the requested file transformation.

4. Restart the XML Transformation Server host and attempt the transformation again.Restarting the server will not affect the XML Transformation Services queue.

A prole error occursErrors related to profiles may occur. For example, if a profile was edited and updatedmanually, there may be issues with the XML file.

There are a number of ways to determine the cause of a profile error, as described inthe following troubleshooting procedure.

To identify the cause of a prole-related error:1. Check the Inbox of the XML Transformation Server system operator for error

messages. Error messages here may indicate the cause of the error.

2. Check the CTS_log.txt or the main Documentum log file, log4j.log (located inC:\Documentum\config), for exceptions.

3. If you suspect the profile itself is the cause of the error, log into either a DocumentumClient (such as Webtop or Digital Asset Manager) as an administrator user or login to Documentum Administrator. Make sure that there are three folders in therepository for XML Transformation Server profiles:• /System/Media Server/Profiles


Troubleshooting

• /System/Media Server/System Profiles• /System/Media Server/Command Line ProfilesThese folders are created when you install XML Transformation Services.Make sure the profile is in the correct folder.

4. Ensure that the command-line file referenced by the profile (dm_media_profileobject) exists in the appropriate folder (listed above) and that the name in the profileis identical to the actual file name.For more information on where profile files should be located, see Modifyingprofiles manually, page 81.

5. Make sure the ProfileSchema.dtd is stored in this repository folder:/System/Media Server/Profiles

6. Restart the XML Transformation Server.

XML Transformation Server cannot add arendition to a particular format

If XML Transformation Server cannot add a rendition to a particular format, first checkthe Inbox of the XML Transformation Server system operator for error messages, andthen check the CTS_log.txt file. Look for a detailed message that describes the problem.For example, the message Object with id=...does not exist would indicate that the objectwas deleted from the repository before the XML Transformation Server could add arendition to it.

XML Transformation Server cannot log in to therepository

XML Transformation Server connects to the repository using a repository SuperUseraccount. If XML Transformation Server cannot log in to the repository, ensure that a validrepository SuperUser is identified for XML Transformation Server to use.

To identify the cause of XML Transformation Server not logging in to therepository:1. Make sure that the repository is running.

2. Check your network connections.

3. Check that the Connection Broker is running.


Troubleshooting

4. Check that the dfc.properties file points to the Connection Broker that recognizesyour repository.

5. Log in to the XML Transformation Server host as an administrator.

6. Open the XML Transformation Server service directory, located in:%CTS_HOME%\config

7. Open the SessionService.xml file in any text or XML editor.

8. Check the values of the CTSServer attributes "userName" and "passwordFile" of theXML Transformation Server element.<CTSServer AttributeName="userName" AttributeValue="<media_superuser_name>"/><CTSServer AttributeName="passwordFile" AttributeValue="<pathto appropriate mspassword.txt>"/>

9. Make sure you have configured the SessionService.xml file to the proper user inthe repository who has SuperUser access. If necessary, check with the repositoryadministrator to verify user name and password information.

10. Save and close the SessionService.xml file.

11. Restart the XML Transformation Server and/or the repository.

CTS Administration Agent givesAGENT_INACCESSIBLE message

If the CTS Administration node in Documentum Administrator (DA) is showing anAGENT_INACCESSIBLE message, it indicates that DA was unable to connect to theagent. This could be as a result of a number of reasons:

1. The server method on the Content Server is not running.

Check the service on the Content Server machine. There should be a service calledDocumentum Java Server Method. Ensure that is started/running.

2. The CTS Administration Agent is not running.

There is a service called Documentum CTS Admin Agent on the CTS machine for theagent. If this service is running, you should be able to ping the agent by opening yourbrowser and pointing it to http://machinename:<port>/CTSAgent/CTSAgent (thedefault port is 9095). It should respond with a page saying "Content TransformationServices Agent" if it is running.

If the Admin Agent is not running, see Starting and stopping the CTS AdministrationAgent, page 42 to start the CTS Admin Agent.


Troubleshooting

3. The server method on the Content Server is not there.

You can look for the server method using Documentum Administrator(Administration > JobManagement >Methods). Do a search for CTSAdminMethod.There should be one result if it is a version 5.3 or higher repository.

4. There is no space left on the CTS Administration Agent machine.

Check the machine to ensure there is available space.

Content Transformation Services fails tofunction

Content Transformation Services fails to function and you receive an error message whenattempting transformations. The error may occur if the Global Registry does not havea Content Transformation Services product (Rich_Media_Services and TransformationDARs) configured against it. The Global Registry is a common repository wherecommonly used DARs are installed.

Ensure Rich_Media_Services and Transformation DARs are run against the GlobalRegistry repository. See instructions in the XML Transformation Services Installation Guide.

Locating application server working folderPerform the following steps if you are unable to locate the current working folder inwhich to place the transformation.properties file:

• Perform any real time request (and let it fail).• Check the log file for the location of the folder.

The log file displays the expected location of the transformation.properties file.• Make sure the transformation.properties are in the right folder.


Troubleshooting


Index

Aactivity templates

attach workflow, 50copying, 49installing, 49uninstalling, 50validating, 49

addingplug-ins, 14repositories, 25

admin password, changing, 45architecture, 13attach workflow

activity templates, 50

Bbatch files, 24

CCan Be Indexed setting, 27changing configuration, 43checked out documents, 15 to 17CHM renditions, 12, 17 to 18COM Class ID for format, 26command-line files, 94

storing, 73Compiled HTML Help, see CHM

renditionsconfiguring

queue item sign-off, 45configuring CTS WebService instance

JBoss, 66other supported applications, 66, 69

configuring XML Transformation Serverchanging login user name, 24changing the logging level, 24changing the maximum number of

queue items, 24changing the notification setting, 24

changing the polling interval, 24changing the queue item expiry, 24changing the system operator, 24

configuring XML Transformation Serviceschanging the repository, 25Configurator, 25using Documentum

Administrator, 25Content Transformation Monitor

Services, 43Content Transformation Services

description, 11error message, 97fails to function, 97format awareness, 12queue, 12scalability, 12

Create New Template command, 27creating

CHM renditions, 17HTML renditions, 16PDF renditions, 15

CTS Activity Templatedocument transformation, 49Documentum Process Builder, 46users, 46workflow parameters, 48working with, 46

CTS Admin Agent, 24CTS Reporting Tool, 50

disable, 51enable, 50viewing reports, 51

CTS Service, changing user, 44CTS web services

architecture, 64asynchronous transformation, 65 to

66configuring CTS WebService

instance, 66, 69DFS, 63


Index

Operations, 63Profile service, 61 to 62synchronous transformation, 65Transformation service, 61 to 62what are, 61

CTS WebService instancelog file, 72

DDAM

modifying transformationprofiles, 74 to 75, 77, 79

using DFC, 13details of a CTS instance, viewing, 42DFC

about, 13installing with XML Transformation

Services, 13Digital Asset Manager, see DAMDITA filters

adding new, 31configuring, 30

DITA source filestransforming, 85

DITA, transform handler, 15dita_transform_chm.xml, configuring, 33dita_transform_command.xml file, 32dita_transform_pdf.xml, configuring, 33dita_transform.xml

adding filters to, 31dita_transform.xml, configuring, 30dm_media_profile object, 81dm_mediaserver_error, 93dm_queue, 16, 18DocBook filters

adding new, 34configuring, 33

DocBook source filestransforming to CHM, 87transforming to HTML, 89transforming to PDF, 91

DocBook transform handler, 15docbook_transform_command.xml

file, 35docbook_transform.xml

adding filters to, 34Documentum Administrator

accessing the configuration screen, 25Create New Format Object page, 26

defining file formats, 26Documentum Foundation Classes, see

DFCDOS file formats, defining, 27DQL

guidelines, 82in profiles, 81query examples, 82r_object_id attribute, 83syntax, 82tips, 82

Eerrors, 93 to 95

dm_mediaserver_error, 24in log files, 42receiving, 24

events, 93dm_mediaserver_error, 24

Ffile formats, 26

creating templates, 27supported as source for CHM, 20supported as source for HTML, 20supported as source for PDF, 20

filename extensions, 26filters

adding product names, 29default, 28definition, 28for DITA transformations, 30, 86,

90 to 91for DocBook transformations, 33in source files, 28

format_token, 82FormatMapperService, updating, 27

GGlobal Registry

CTS product, 97

HHTML renditions, 12, 16 to 17HyperText Markup Language, see HTML

renditions


Index

IignoreItemsToSignOffLimit, 45Inbox notifications, 24, 93 to 94

changing in DA, 24configuring, 35settings, 35

Indexwith Filter setting, 27with Rendition setting, 27

input_doctype_family name, 73installation

plug-ins, 14scalability, 12typical, 13

installingactivity templates, 49

instance details, viewing, 42

LLegacy profiles

migrating, 57load balancing, 44locked documents, 15 to 17log file

CTS WebService instance, 72log files, 93

viewing, 42logging level, 44

changing, 24login, 95login user, identifying, 24

MMacintosh Creator format setting, 27Macintosh Type format setting, 27markerInterval, 45Media_Server_Log.txt, 93Migration utility

log file, 57migrating profiles, 57

MIME type, 26modifying

system profiles, 74modifying system profiles, 81modifying transformation profiles, 81monitor services, 43multiple servers, 44

Nnotifications

changing in DA, 24configuring, 35

Oobjects, 15, 17 to 18

dm_media_profile, 81

Ppage_modifier_token, 82page_token, 82password, changing, 42, 45PDF renditions, 15, 17placeholders, 82plug-ins

adding, 14description, 14installation of, 14standard, 14using command-line files, 73

polling interval, changing, 24Portable Document Format, see PDF

renditionsProfile Editor

build profile, 75, 77, 79chain profile, 75, 77, 79modifying profiles, 75, 77, 79sequence profile, 75, 77, 79specialized profile, 75, 77, 79

Profile serviceaddProfile operation, 62getProfileById operation, 62getProfileByName operation, 62Operations, 62 to 63removeProfile operation, 62updateProfile operation, 62what is, 61

profile_audience filter, 28profile_os filter, 28profile_product filter, 28

adding names to, 29profile_revision filter, 28profiles, 94

migrating, 57modifying, 74, 81using DQL, 81

ProfileSchema.dtd file, 29 to 30


Index

Qqueue

objects, 13removing unsupported formats

from, 12queue items

changing the expiry, 24changing the maximum number

allowed, 24configuring sign-off, 45

queue marker mechanism, 45queue, managing, 52

Rr_object_id, 83refreshing XML Transformation

Services, 42registry ID for format, 26removing a repository, 25renditions, 95

viewing, 92repository, 95

adding, 25changing, 25

Sscalability of Content Transformation

Services, 12servers, multiple, 44setPassword utility, 45settings

Can Be Indexed, 27Default File Extension, 26Index with Filter, 27Index with Rendition, 27MIME type, 26

source formats supported, 20starting XML Transformation

Services, 42 to 43stopping XML Transformation

Services, 42 to 43sysobject_id_token, 82system architecture, 13system operator user, identifying, 24system profiles, modifying, 74, 81

Ttokens, 82Transform DocBook to HTML.xml,

configuring, 33transform handlers, 14Transformation node, 52transformation profiles, 94

command-line files, 73transformation queue, 52Transformation queue

changing queue priority, 53configuring queue management

fields, 55deleting queue item, 55removing queue management

field, 56viewing details of queue item, 54viewing transformations, 53

Transformation serviceaddJob operation, 63cleanUpJobs operation, 63CTS web services, 62deleteJob operation, 63getJobInfo operation, 63importAndAddJob operation, 63transformJob operation, 63what is, 62

Transformation Servicesextending, 14requirements, 14role in XML Transformation

Services, 13transformations, 94

DITA source files, 85DocBook source files, 87performing, 13, 85viewing completed, 92

troubleshooting, 93 to 94with log files, 42

Uuninstalling

activity templates, 50user transformations, 85users, changing

for CTS Service, 44for repository login, 24system operator, 24


Index

Vvalidating

activity templates, 49

WWDK, relation to XML Transformation

Services, 13Web Development Kit, seeWDKWindows Service, 12

XXML transform handler, 15XML Transformation Server, 93

position in installation, 13

XML Transformation Servicesarchitecture, 13changing settings, 43Configurator, 25description, 12environment, 13features, 19refreshing, 42starting, 42 to 43stopping, 42 to 43

ZZip files, 17 to 18ZIP renditions, 12


xml transformation services administration guide

Documents