EMC® Documentum® XML Transformation Services Version 6
Administration Guide P/N 300-005-309
EMC Corporation Corporate Headquarters: Hopkinton, MA 01748-9103 1-508-435-1000 www.EMC.com
Copyright © 2007 EMC Corporation. All rights reserved. Published August 2007 EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. All other trademarks used herein are the property of their respective owners.
Table of Contents
Preface Chapter 1
Chapter 2
Chapter 3
...........................................................................................................................
7
................................................. What is Content Transformation Services? ..................................................... Content Transformation Services scalability ............................................. What is XML Transformation Services? ........................................................ XML Transformation Services components ............................................... XML Transformation Services environment .......................................... XML Transformation Server ................................................................ Documentum Foundation Classes ....................................................... XML Transformation Services plug-in .................................................. Transform handlers ................................................................................ How XML Transformation Services works ............................................... How XML Transformation Services creates PDF renditions ................... How XML Transformation Services creates HTML renditions ................ How XML Transformation Services creates CHM renditions ..................... Features of XML Transformation Services .................................................... Supported transformations by source and target formats ..............................
9
XML Transformation Services Overview
9 10 10 11 11 11 12 12 13 13 13 14 15 17 18
Conguring XML Transformation Services ........................................... Configuring XML Transformation Services through Documentum Administrator ............................................................................................ Starting and stopping the CTS Administration Agent ............................... Accessing the configuration screen in Documentum Administrator ............
21 22 23
Adding or removing repositories serviced by XML Transformation Services ..................................................................................................... Defining file formats and DOS extensions .................................................... Configuring filters ...................................................................................... Adding product names to the product filter ............................................. Configuring other DITA filters ................................................................. Configuring other DocBook filters ........................................................... Configuring Inbox notifications ...................................................................
23 24 26 27 28 31 33
Administering XML Transformation Services
21
........................................ 37
Administering XML Transformation Services through Documentum Administrator ....................................................................... Starting and stopping the CTS Administration Agent ............................... Starting and stopping XML Transformation Services ..................................... Altering timing and operational parameters ................................................. Controlling the logging level ...................................................................
37 38 39 39 40
Managing multiple servers .......................................................................... Changing the CTS Service user after installation ........................................... Changing the CTS administrator password ..................................................
40 40 40
EMC Documentum XML Transformation Services Version 6 Administration Guide
3
Table of Contents
Conguring the queue marker mechanism to manage queue item sign-off ......................................................................................................
41
Working with the CTS Activity Template in Documentum Process Builder....................................................................................................... Making the CTS Activity Template available to users ................................ Making transformation profiles available for use with the template ................................................................................................ Transformation profiles with no parameters ......................................... Using the CTS Activity Template ............................................................. Using the CTS Reporting Tool ..................................................................... Enabling and disabling the CTS Reporting Tool ........................................ Viewing the CTS Reporting Tool report .................................................... Managing the transformation queue ............................................................ Viewing transformation requests in the queue .......................................... Changing a queue item’s priority ............................................................. Viewing details of a queue item ............................................................... Deleting a pending queue item ................................................................ Configuring additional queue management fields..................................... Removing a queue management field ......................................................
43 43 43 44 45 45 46 47 48 48 49 50 50
Working with Proles ............................................................................ Understanding command-line files .............................................................. Building and modifying profiles with Profile Editor ...................................... Editing a profile...................................................................................... Building a new profile............................................................................. Building a chain profile ........................................................................... Building a parallel profile ........................................................................ Modifying profiles manually .......................................................................
53 53 54 54 55 57 59 61
Using DQL in profiles ................................................................................. The dql attribute value syntax ................................................................. DQL guidelines ...................................................................................... DQL query examples .............................................................................. Querying the r_object_id attribute ...........................................................
61 62 62 62 63
Chapter 5
Performing Transformations ................................................................. Transforming DITA files .............................................................................. Transforming DocBook files ........................................................................ Transforming DocBook files to CHM ....................................................... Transforming DocBook files to HTML ...................................................... Transforming DocBook files to PDF ......................................................... Viewing renditions .....................................................................................
65 65 67 67 69 70 72
Chapter 6
Troubleshooting .................................................................................... Error events and log files ............................................................................. A transformation request fails ..................................................................... A profile error occurs .................................................................................. XML Transformation Server cannot add a rendition to a particular format........................................................................................................
73 73 74 74
XML Transformation Server cannot log in to the repository ........................... CTS Administration Agent gives AGENT_INACCESSIBLE message.............. Content Transformation Services fails to function .........................................
75 76 77
Chapter 4
4
42 42
75
EMC Documentum XML Transformation Services Version 6 Administration Guide
Table of Contents
List of Figures
Figure 1. Figure 2. Figure 3.
Typical XML Transformation Services installation ............................................. Processing a request for a PDF rendition .......................................................... Processing a request for an HTML rendition.....................................................
11 14 15
Figure 4.
Processing a request for a CHM rendition ........................................................
17
EMC Documentum XML Transformation Services Version 6 Administration Guide
5
Table of Contents
List of Tables
17
Table 3.
XML Transformation Services features ............................................................. Supported transformations with XML Transformation Services by source and target formats ............................................................................ File format attributes ......................................................................................
Table 4. Table 5.
Documentum format mapping ........................................................................ Inbox notification settings ...............................................................................
26 33
Table 1. Table 2.
6
18 24
EMC Documentum XML Transformation Services Version 6 Administration Guide
Preface
This guide provides step-by-step procedures for configuring and administering Documentum XML Transformation Services. This manual also includes information about modifying profiles to extend the 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 Notes
See the appropriate Documentum product documentation for information on related Documentum products. For example, many administration and configuration tasks for XML Transformation Services are best performed through Documentum Administrator; consult the Documentum Administrator User Guide for guidance.
Intended audience The primary audience for this guide is the system administrator who maintains this software. The secondary audience is the system integrator who wishes to extend XML Transformation Services functionality. Familiarity with Microsoft Windows and the Documentum system is essential.
Revision history The following changes have been made to this document.
EMC Documentum XML Transformation Services Version 6 Administration Guide
7
Preface
8
Revision date
Description
August 2007
Initial publication for version 6 product release.
EMC Documentum XML Transformation Services Version 6 Administration Guide
Chapter 1 XML Transformation Services Overview
This chapter contains a brief overview of XML Transformation Services. It gives a basic description of the Documentum environment and relates the XML Transformation Services components within the installation. This chapter contains the following sections: •
What is Content Transformation Services?, page 9 is a brief overview of Content Transformation Services and the set of products that the term is commonly used to describe. XML Transformation Services is a product within the Content Transformation Services suite.
•
What is XML Transformation Services?, page 10 is an introduction to XML Transformation Services with a general description of its major components, and a brief explanation of how XML Transformation Services works and integrates with other Documentum products.
•
Features of XML Transformation Services, page 17 describes the functionality available with XML Transformation Services.
•
Supported transformations by source and target formats, page 18 includes a table of supported transformations by source and target formats.
What is Content Transformation Services? Content Transformation Services (CTS) is a suite of Documentum server products that perform transformations and analysis on repository content. CTS includes these main products: •
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, Media Transformation Services may have additional transformation services installed, such as Audio/Video Transformation Services (AVTS) or Medical Imaging Transformation
EMC Documentum XML Transformation Services Version 6 Administration Guide
9
XML Transformation Services Overview
Services (MITS). These components supplement the features already provided by the base product, according to your organization’s requirements.
Content Transformation Services scalability Content Transformation Services (CTS) products allow for a high level of scalability. All CTS products run under the same Windows Service on the CTS host. This means that stopping or starting the CTS service stops or starts all the CTS products on that host. For example, if your CTS host contains XML Transformation Services and Media Transformation Services, stopping the CTS service stops both products. Each CTS product can be configured for multiple repositories. If you have one installation of a product on a host, that installation can be configured against multiple repositories. CTS scalability also allows for several instances of Content Transformation Services products on different hosts to be configured for the same repository. This means that your 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 to recognize which file formats it is capable of processing. Items that cannot be processed successfully will be removed from the queue automatically. A check for unprocessed items is performed periodically.
What is XML Transformation Services? XML Transformation Services is server software that generates copies of documents in Portable Document Format (PDF), HyperText Markup Language (HTML), ZIP, and Compiled HTML Help (CHM). You can use Documentum client applications to request such a copy (called a rendition) of a document stored in a Documentum repository. Designed primarily for technical publication organizations, XML Transformation Services is part of a seamless approach to storing, managing, and transforming XML content in either DocBook or DITA formats. Refer to the XML Transformation Services Release Notes for details about the XML standards supported in this release.
10
EMC Documentum XML Transformation Services Version 6 Administration Guide
XML Transformation Services Overview
XML Transformation Services components XML Transformation Services is an added component to your basic Documentum installation that includes Content Server and defined repositories with file stores. The following sections detail the main components that comprise a XML Transformation Services installation.
XML Transformation Services environment Figure 1, page 11 shows a typical XML Transformation Services installation on the Documentum 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 or request file transformations, the Content Server stores those register and request objects in a queue. The XML Transformation Server will poll that queue intermittently, looking for register and request objects. The file is then passed to the appropriate Transformation Service plug-in for processing. When the processing is complete, the XML Transformation Server updates the original objects with new renditions or creates the new objects, as requested. The objects are
EMC Documentum XML Transformation Services Version 6 Administration Guide
11
XML Transformation Services Overview
saved to the repository and the requests are removed from the queue. The objects are then ready for use.
Documentum Foundation Classes The Documentum Foundation Classes (DFC) are a set of Java classes that provide access to Content Server functionality. Web-based applications, such as Digital Asset Manager and Web Publisher, make calls directly to the DFC or indirectly through the Web Development Kit (WDK). DFC must be installed on the XML Transformation Services host. If you are installing XML Transformation Services on a host that already has the DFC, XML Transformation Services 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 the DFC 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 the Documentum Download Center at https://emc.subscribenet.com/control/dctm/index for more information on migration issues. Follow the Documentum Foundation > Documentation for Documentum 6 link. Any applications that were dependent upon the older version of the DFC will have to be upgraded as well. For more information on the DFC and their effect on other applications, 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 files from 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.
Plug-ins are extensible. You can configure plug-in types and formats, and you can add new plug-ins to the system to support new file formats as required. Information about creating and adding new plug-ins is contained in the Content Transformation Services SDK Development Guide, or contact your Documentum account or support representative for more information.
12
EMC Documentum XML Transformation Services Version 6 Administration Guide
XML Transformation Services Overview
Transform handlers Unique to XML Transformation Services is the use of transform handlers. While other Content Transformation Services plug-ins perform transformations directly, the XPUB plug-in delegates transformation requests to the transform handlers. Each doctype family supported by XML Transformation Services has their own transform handler. The following transform handlers are installed with XML Transformation Services: •
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 XSL stylesheets.
How XML Transformation Services works The following sections detail how XML Transformation Services creates renditions in PDF, HTML, and CHM formats.
How XML Transformation Services creates PDF renditions The following steps describe how XML Transformation Services produces PDF renditions in response to client requests: 1.
The client application sends the rendition request to the Documentum Content Server. Note: XML Transformation Services modifies the document object, so it cannot process 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 retrieves any pending requests.
4.
When XML Transformation Services finds a PDF rendition request in the queue, it checks the input_doctype_family name token to distinguish between a DITA and DocBook file. The request is passed to the appropriate transform handler for the document.
5.
The transform handler generates a PDF rendition based on what the default profiles specify.
EMC Documentum XML Transformation Services Version 6 Administration Guide
13
XML Transformation Services Overview
6.
Content Server adds the PDF renditions to the object in the repository. An object represents a parent file, with all of its associated graphics, text, and renditions, in the repository. Once a rendition has been added to the object, users can view the rendition from the client application. Each time a transformation is performed, an additional rendition is created for the source file.
Figure 2, page 14 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 HTML renditions 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).
14
2.
Content Server stores the request in a special queue called dm_queue.
3.
XML Transformation Server polls dm_queue at predefined intervals, and retrieves any pending requests.
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 and DocBook file. The request is passed to the appropriate transform handler.format of the document.
EMC Documentum XML Transformation Services Version 6 Administration Guide
XML Transformation Services Overview
5.
6.
XML Transformation Services invokes the corresponding application to open the file and then saves an HTML version. •
If the result is a single HTML file, 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 the application creates to contain these files.
Content Server adds the HTML or Zip file to the repository as a rendition of the document object. An object represents a parent file, with all of its associated graphics, text, and renditions, in the repository. Once a rendition has been added to the object, users can view the rendition from the client application. Each time a transformation is performed, an additional rendition is created for the source file.
Figure 4, page 17 illustrates this rendition process. Figure 3. Processing a request for an HTML rendition
How XML Transformation Services creates CHM renditions The following steps describe how XML Transformation Services produces CHM renditions in response to client requests: 1.
The client application sends the rendition request to the Content Server.
EMC Documentum XML Transformation Services Version 6 Administration Guide
15
XML Transformation Services Overview
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.
3.
XML Transformation Server polls dm_queue at predefined intervals, and retrieves any pending requests.
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 DITA and DocBook file. The request is passed to the appropriate transform handler.format of the document.
5.
XML Transformation Services invokes the corresponding application to open the file and then saves an CHM version.
6.
•
If the result is a single CHM file, 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 the application creates to contain these files.
Content Server adds the CHM or Zip file to the repository as a rendition of the document object. An object represents a parent file, with all of its associated graphics, text, and renditions, in the repository. Once a rendition has been added to the object, users can view the rendition from the client application. Each time a transformation is performed, an additional rendition is created for the source file.
Figure 4, page 17 illustrates this rendition process.
16
EMC Documentum XML Transformation Services Version 6 Administration Guide
XML Transformation Services Overview
Figure 4. Processing a request for a CHM rendition
Features of XML Transformation Services The following are the features that XML Transformation Services offers. Table 1. XML Transformation Services features
Feature
Comments
Runs as a Windows Service and intelligently handles exceptions raised by native applications. Transforms XML, DITA, and DITAMAP files into PDF, HTML, ZIP*, and Compiled HTML Help (CHM).
XML source files in DITA and DocBook standards are supported.
Filters the output based on a variety of parameters.
By default, filters for operating systems, audience levels, revisions, and product names are available. These filters are configurable. See Configuring filters, page 26 for details.
Creates a new rendition each time a file is transformed.
EMC Documentum XML Transformation Services Version 6 Administration Guide
17
XML Transformation Services Overview
Feature
Comments
Transforms a document as part of a business workflow process using the CTS Activity Template.
CTS Activity Template is included. Profile configuration required. See Working with the CTS Activity Template in Documentum Process Builder, page 42 for details. See XML Transformation Services Installation Guide for installation instructions.
Integrates with entire Documentum product suite. * ZIP output is valid for DITA source files only.
Supported transformations by source and target formats The supported transformations depend upon the installation of a variety of applications on the XML Transformation Services host. For more information, see the XML Transformation Services Release Notes. With the required supporting applications installed, XML Transformation Services can perform the following transformations. Table 2. Supported transformations with XML Transformation Services by source and target formats
18
Source format (input)
XML standard
Target formats (output)
XML
DITA
PDF, HTML, ZIP
DocBook
PDF, HTML, Compiled HTML Help (CHM)
EMC Documentum XML Transformation Services Version 6 Administration Guide
XML Transformation Services Overview
Source format (input)
XML standard
Target formats (output)
DITA
DITA
PDF, HTML, ZIP
DITAMAP
DITA
PDF, HTML, Compiled HTML Help (CHM), ZIP
EMC Documentum XML Transformation Services Version 6 Administration Guide
19
XML Transformation Services Overview
20
EMC Documentum XML Transformation Services Version 6 Administration Guide
Chapter 2 Conguring XML Transformation Services
This chapter contains instructions for configuring XML Transformation Services. The following sections are included in this chapter: •
Configuring XML Transformation Services through Documentum Administrator, page 21
•
Adding or removing repositories serviced by XML Transformation Services, page 23
•
Defining file formats and DOS extensions, page 24
•
Configuring filters, page 26
•
Configuring Inbox notifications, page 33
Conguring XML Transformation Services through Documentum Administrator Many configuration tasks for XML Transformation Services can now be done through the CTS Administration component of Documentum Administrator. You must have access to Documentum Administrator and the repositories to which XML Transformation Services is configured. The CTS Administration component appears in Documentum Administrator if at least one instance is installed and configured on a repository to which it is connected. This check is done through executing the DQL/DFC call to find the presence of at least one cts_instance_info object in the repository. The following XML Transformation Services configuration tasks can be performed through the Documentum Administrator client, in the CTS Administration Node:
EMC Documentum XML Transformation Services Version 6 Administration Guide
21
Conguring XML Transformation Services
•
Change the system operator user. The system operator is the name of the user who receives 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 the XML Transformation Server system operator (sysOpUser). The event appears as an error 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 Server creates queue items and appends them to the dm_mediaserver queue or dm_autorender_win31 queue, depending on the type of request. XML Transformation Server uses a queue polling mechanism to look for items in the queue that it has to process. When XML Transformation Server finds items in any of these queues, it proceeds with processing.
•
Change the logging level. The logging level value controls how much information will be recorded in the CTS log files, which XML Transformation Services uses. Log files can be used to troubleshoot the system.
•
Change the system notification setting. The notification setting controls whether success notifications should be sent to each individual user requesting a transformation through a CTS product.
•
Change the maximum number of queue items. This value controls how many items the XML Transformation Services instance adds for processing each time it polls the queue.
•
Change the queue item expiry. This value controls the amount of time an item will be sitting in a queue before being deleted from the queue.
The Documentum Administrator User Guide provides more information about these configuration tasks.
Starting and stopping the CTS Administration Agent In order to use the Content Transformation Services Administration component in Documentum Administrator, it is necessary to have the CTS Admin Agent running on the CTS host machine. The Admin Agent can be stopped or started either from the Windows Start menu, or by running a batch file.
To start/stop the CTS Admin Agent through the Start menu: 1.
22
Log in to the XML Transformation Services host.
EMC Documentum XML Transformation Services Version 6 Administration Guide
Conguring XML Transformation Services
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 Documentum Administrator You can perform the tasks outlined in Configuring XML Transformation Services through Documentum Administrator, page 21 through the configuration screen in Documentum 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 configuration tasks.
Adding or removing repositories serviced by XML Transformation Services During installation, XML Transformation Services is configured to communicate with single or multiple repositories. You can add or remove a repository by running the XML Transformation Services Configurator (accessible through the Windows menu at Start > Programs > Documentum > XML Transformation Services Instance Add or Remove).
EMC Documentum XML Transformation Services Version 6 Administration Guide
23
Conguring XML Transformation Services
For information on the Configurator 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 remove support for XML Transformation Services.
Dening le formats and DOS extensions You must define file formats and DOS file extension pairs in the repository for all source document types that you want XML Transformation Services to recognize. In addition, if the DOS file extension differs from the Documentum format name, you must update the 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 24.
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
24
COM Class ID
Component Object Model (COM) registry ID for the format
MIME Type
The Multimedia Internet Mail Extension (MIME) designation for the content type
EMC Documentum XML Transformation Services Version 6 Administration Guide
Conguring XML Transformation Services
Field
Value
Windows Application
Name of an application to launch when users select a document in the format represented by the format object
Is Hidden
Used by client applications
Macintosh Creator*
Information used internally for managing Macintosh resource files
Macintosh Type*
Information used internally for managing Macintosh resource files
* The Macintosh Creator and Type values are necessary for users to access files in this format from Macintosh clients. 5.
If the format is indexable, define the indexing options. a.
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 rendition format from the list box. This is the format in which the document will be indexed if its original format is not used for indexing. If you are indexing the PDF text rendition of documents in this format, set this to pdftext.
6.
Click Create. A confirmation page appears. You can create a new template for this format by selecting Create New Template for this Format.
The following procedure is required only if the DOS file format differs from the Documentum format name in Content Server. See Table 4, page 26 for a listing of format names 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 section, using the following syntax:
For example, the entry for DITA topic files is:
4.
Save and close the FormatMapperService.xml file.
EMC Documentum XML Transformation Services Version 6 Administration Guide
25
Conguring XML Transformation Services
Table 4, page 26 lists some examples of the format mapping used in Documentum systems. Use these format names in DQL. Table 4. Documentum format mapping
Format
Documentum name
DITA
ditatopic
DITAMAP
ditamap
XML
xml
Conguring lters Filters allow you to configure the output to include or exclude specific content that has been tagged within the source document. For example, a user guide may have content that applies to specific operating systems on which the application is installed. If the content pertaining to those operating systems is tagged as such within the source file, the output 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 your organization.
If any of these default filters are appropriate for your organization, you must ensure that the source documents are profiled accordingly. To use the operating system profile, for instance, you must tag sections within your source documents with operating system names. Consult the documentation for your authoring system to determine how to profile your source documents. For many organizations, these filters will require modification, or new filters will be needed.
26
EMC Documentum XML Transformation Services Version 6 Administration Guide
Conguring XML Transformation Services
One transformation profile controls all DITA filters, while three different profiles are required for DocBook transformations. Separate procedures are provided for both DITA and DocBook filter configurations. This section covers the following topics: •
Adding product names to the product filter, page 27
•
Configuring other DITA filters, page 28
•
Configuring other DocBook filters, page 31
Adding product names to the product lter Since each organization will have a unique set of product names for which to filter, you must add the appropriate product names to the transformation profiles. Note: By default, the profiles have no product names specified. If you do not add product names as outlined below, users can simply enter the product name in a text box when they perform transformations. However, this approach could lead to user errors if incorrect product names are entered. Configuring the product names in the profiles is 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 in the 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 on the transformations your organization will be using.
Note: If these files are not immediately visible, select Show All Objects and Versions 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 tokens to the profile_product parameter.
EMC Documentum XML Transformation Services Version 6 Administration Guide
27
Conguring XML Transformation Services
For example, if you want to filter content based on model number, you could add values as follows: Model A Model B Model C Model D
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 are requesting 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.
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 in the future can reference the DTD.
4.
Check out the dita_transform.xml file. Note: If this file is not immediately visible, select Show All Objects and Versions from the Show list box.
5.
Open the profile in an XML or text editor.
6.
Locate the filter parameter you wish to modify within the section. For example, the revision filter appears as follows: New Changed Deleted Final
7.
Add, modify, or delete a value within the list, being careful to follow the proper syntax. For example, you could change the values for profile_revision, as follows: First draft Technical review Approved
8.
Save your changes.
9.
Check in the profile.
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.
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 in the future can reference the DTD.
4.
Check out the dita_transform.xml file. Note: If this file is not immediately visible, select Show All Objects and Versions from the Show list box.
EMC Documentum XML Transformation Services Version 6 Administration Guide
29
Conguring XML Transformation Services
5.
Open the profile in an XML or text editor.
6.
Add a parameter for the filter you wish to add. For example, to add a filter based on application servers, the new parameter might appear as follows: BEA Oracle Sun One Tomcat
7.
Save your changes.
8.
Check in the profile.
9.
Navigate to /System/Media Server/Command Line Files.
10. Check out the dita_transform_command.xml file. Note: If this file is not immediately visible, select Show All Objects and Versions from the Show list box. 11. Open the profile in an XML or text editor. 12. In the section, add the new filter. This illustrates the entry for the application server example:
13. In this same file, add an entry to the section. Continuing the application server example, this addition would appear as follows:
14. Save your changes. 15. Check in the profile. 16. Stop and restart the transformation server service. The new filter will now appear when users request transformations for DITA files.
30
EMC Documentum XML Transformation Services Version 6 Administration Guide
Conguring XML Transformation Services
Conguring other DocBook lters Three profile files handle DocBook transformations, based on the output format: •
docbook_transform_chm
•
docbook_transform_html
•
docbook_transform_pdf
Each of these profiles contains a unique set of parameters. They also include the standard four filters as for DITA files.
To modify an existing DocBook lter: 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 in the future can reference the DTD.
4.
Check out the docbook_transform file you wish to modify. Note: If these files are not immediately visible, select Show All Objects and Versions from the Show list box.
5.
Open the profile in an XML or text editor.
6.
Locate the filter parameter you wish to modify within the section. For example, the audience filter appears as follows: Expert Intermediate Beginner
7.
Add, modify, or delete a value within the list, being careful to follow the proper syntax. For example, you could change the values for profile_audience, as follows: User Administrator Developer
8.
Save your changes.
9.
Check in the profile.
10. Stop and restart the transformation server service. The modified values will now appear when users request transformations for DocBook files.
To add a new lter for DocBook source les: 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 in the future can reference the DTD.
4.
Check out the docbook_transform file for which to add a filter. Note: If these files are not immediately visible, select Show All Objects and Versions from the Show list box.
5.
Open the profile in an XML or text editor.
6.
Add a parameter for the filter you wish to add. For example, if your documents contain different regulatory statements pertaining to different countries, you might require a country filter. Such a parameter might appear as follows: USA Canada Mexico
32
EMC Documentum XML Transformation Services Version 6 Administration Guide
Conguring XML Transformation Services
7.
Save your changes.
8.
Check in the profile.
9.
Navigate to /System/Media Server/Command Line Files.
10. Check out the docbook_transform_command.xml file. Note: If this file is not immediately visible, select Show All Objects and Versions from the Show list box. 11. Open the profile in an XML or text editor. 12. In the section, add the new filter. This illustrates the entry for the country example:
13. In this same file, add an entry to the section. Continuing the country example, this addition would appear as follows:
14. Save your changes. 15. Check in the profile. 16. Stop and restart the transformation server service. The new filter will now appear when users request transformations for DocBook files.
Conguring Inbox notications When transformation requests fail, the XML Transformation Server sends notifications to the 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 success notifications can be suppressed for all users, failure notifications are sent to admin users regardless of the setting. Table 5, page 33 outlines these behaviors. Table 5. Inbox notication settings
Notification
Setting
User(s) notified
Success
Yes
Regular user
No
none
EMC Documentum XML Transformation Services Version 6 Administration Guide
33
Conguring XML Transformation Services
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 the notifySuccessMessage parameter to the following:
To turn off notifications for successful transformations, you need to set the notifySuccessMessage parameter to the following:
Note: There are two tags for each repository that is configured. You must modify the notifySuccessMessage parameter within each 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 the notifySuccessMessage parameter to the following:
To turn off notifications for failure transformations, you need to set the notifySuccessMessage parameter to the following:
Note: There are two tags for each repository that is configured. You must modify the notifySuccessMessage parameter within each tag.
34
EMC Documentum XML Transformation Services Version 6 Administration Guide
Conguring XML Transformation Services
4.
Save and close the CTSServerService.xml file.
EMC Documentum XML Transformation Services Version 6 Administration Guide
35
Conguring XML Transformation Services
36
EMC Documentum XML Transformation Services Version 6 Administration Guide
Chapter 3 Administering XML Transformation Services
This chapter contains information about XML Transformation Services administration options. The following sections are included in this chapter: •
Administering XML Transformation Services through Documentum Administrator, page 37
•
Starting and stopping XML Transformation Services, page 39
•
Altering timing and operational parameters, page 39
•
Managing multiple servers, page 40
•
Changing the CTS Service user after installation, page 40
•
Changing the CTS administrator password, page 40
•
Conguring the queue marker mechanism to manage queue item sign-off, page 41
•
Working with the CTS Activity Template in Documentum Process Builder, page 42
•
Using the CTS Reporting Tool, page 44
•
Managing the transformation queue, page 46
Administering XML Transformation Services through Documentum Administrator Some administration tasks for XML Transformation Services can now be done through the Content Transformation Services Administration component of Documentum Administrator. The CTS Administration component appears in Documentum Administrator if at least one instance is installed and configured on a repository to which it is connected. This check is done through executing the DQL/DFC call to find the presence of at least one cts_instance_info object in the repository. The following XML Transformation Services administration tasks can be performed through Documentum Administrator:
EMC Documentum XML Transformation Services Version 6 Administration Guide
37
Administering XML Transformation Services
•
Change your password. Alternatively, this task can be done using the setPassword utility. Note that the system administrator must also change the password on the server.
•
View log files. Log files are created for each plug-in. The contents and detail level of each log file depend on the log file setting you have chosen for the XML Transformation Services instance.
•
View details of an instance. Details include each CTS product that is configured for a repository, the version number of each product, the name of the host machine for each product, its current status (running or stopped), the time it was last started, the number of queued items for the instance, and the number of items processed by the 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 running on the host. This is because all CTS products on a host use the same CTS Windows service. Starting and stopping the CTS Windows service can also be done manually, on the host machine. See Starting and stopping XML Transformation Services, page 39.
Starting and stopping the CTS Administration Agent In order to use the Content Transformation Services Administration component in Documentum Administrator, it is necessary to have the CTS Admin Agent running on the CTS host machine. The Admin Agent can be controlled either from the Windows 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.
38
EMC Documentum XML Transformation Services Version 6 Administration Guide
Administering XML Transformation Services
Starting and stopping XML Transformation Services When you restart the XML Transformation Server host, the XML Transformation Server will start automatically. You may also start and stop the XML Transformation Server manually, using the following procedure. This may be necessary after modifying a transformation profile, for example.
To start/stop XML Transformation Services: 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 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 Monitor Services, restarts XML Transformation Services if it stops unexpectedly. Since the monitor is set to run automatically by default, you will not typically need to access it. It is located under Windows Services.
Altering timing and operational parameters The sections that follow explain how to alter the timing and operational parameters that can be changed. The following is the basic procedure to follow when changing timing and 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 setting parameters.
3.
Restart the XML Transformation Server.
EMC Documentum XML Transformation Services Version 6 Administration Guide
39
Administering XML Transformation Services
Controlling the logging level The logging level can be controlled by modifying the log4j.properties file, available in the Documentum user directory (such as C:\Documentum\config). By default it is set to INFO level. To get more logging information, modify this level to DEBUG. Note: This task can also be performed through the Content Transformation Services Administration component in Documentum Administrator. See Configuring XML Transformation Services through Documentum Administrator, page 21.
Managing multiple servers The standard installation for XML Transformation Services consists of one repository with one server. Additional servers can be added to an active repository to enhance its performance. Load balancing can optimize performance by spreading transformation requests 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 a standard load balancing strategy. The ideal load balancing strategy depends upon your environment and the specific servers in use. Contact your Documentum consulting representative for load balancing guidance.
Changing the CTS Service user after installation In certain situations, you may need to change the CTS Service user account after XML Transformation Services has been installed and configured. This may be necessary for security reasons, for example. It is not necessary to uninstall and reinstall XML Transformation Services to make this change. Simply ensure that the new user has full COM access permissions for the rendering software being used by XML Transformation Services.
Changing the CTS administrator password You can change the CTS administrator’s password by running the setPassword utility. The password also must be changed on Content Server.
40
EMC Documentum XML Transformation Services Version 6 Administration Guide
Administering XML Transformation Services
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\\CTSServerScript\bin > setPassword
5.
Restart Content Transformation Services.
Note: It is also possible to change the password in Documentum Administrator instead of running the setPassword utility (Step 3 and Step 4 above). You must still perform the other steps in this procedure.
Conguring the queue marker mechanism to manage queue item sign-off This procedure applies only if you have different CTS products polling the same repository but installed on separate hosts. The queue marker mechanism analyzes queue items and marks those that can be executed by the CTS instance, preventing items from being prematurely expired by a CTS instance that cannot handle them. The marker tasks run with their own sessions. 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 set to "YES", the marker thread will be created. By default, the value is set to "NO", and there 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 system configuration. On a system with similar CTS products polling the same queue, the marker 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 might expire items (because it cannot handle them) when the instance that could handle them is busy. In this case, the marking mechanism should be turned on for those instances that could process the items.
EMC Documentum XML Transformation Services Version 6 Administration Guide
41
Administering XML Transformation Services
Working with the CTS Activity Template in Documentum Process Builder The CTS Activity Template allows users to add a content transformation as part of a workflow process. With this version of XML Transformation Services the CTS Activity Template is available for use with Documentum Process Builder. XML Transformation Services profiles need to be customized to make them available for use with the CTS Activity Template. See Building and modifying profiles with Profile Editor, page 54 for instructions on how to edit a profile using the Profile Editor. The following section outlines the procedures required to use the activity template. It is meant to supplement — not replace — the information in the Documentum Process Builder documentation set. You should be familiar with the Documentum Process Builder application and have access to the Documentum Process Builder Installation Guide, Documentum Process Builder User Guide, and Documentum Process Builder Release Notes.
Making the CTS Activity Template available to users Users can begin using the CTS Activity Template after: •
All installation procedures (as described in the 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 Documentum Process Builder (see below).
•
XML Transformation Services profiles need to be customized with default values to make them available for use with the CTS Activity Template. See Building and modifying profiles with Profile Editor, page 54 for instructions on how to edit a profile using the Profile Editor.
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 available activity palettes, and the list box on the right displays the palettes currently being displayed in Documentum Process Builder. Note: Preferences are saved separately for each user. The list of palettes may differ if you log in as a different user.
42
EMC Documentum XML Transformation Services Version 6 Administration Guide
Administering XML Transformation Services
3.
To display the CTS palette in Documentum Process Builder, highlight its name in the 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 different preferences.
Making transformation proles available for use with the template Only profiles that include user-defined parameters are available for CTS Activity Template: •
Link the profiles from /System/Media Server/System Profiles to the /System/CTSActivity folder in the repository. Any changes made to the profiles in the Media Server folder are automatically reflected in the /System/CTSActivity folder.
Transformation proles with no parameters In XML Transformation Services profiles do not include default parameters. Profile parameters need to be entered manually.
Using the CTS Activity Template This section describes the CTS Activity Template and the special workflow parameters associated with it. In Documentum Process Builder, activities are the tasks that comprise the workflow. Most of the configuration of the workflow relates to configuring its activities. You configure activities using the Activity Inspector. The Activity Inspector has several tabs, each corresponding to one aspect of activity configuration. When you select the CTS Activity Template, the following tabs are available: •
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.
EMC Documentum XML Transformation Services Version 6 Administration Guide
43
Administering XML Transformation Services
•
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.
•
The Display 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.
The Documentum Process Builder User Guide describes all of these tabs – with the exception of 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 CTS Parameters tab in the Activity Inspector.
To add a document transformation to a business process: 1.
In the Activity Inspector, select the CTS Parameters tab.
2.
Choose a transformation profile from the Profile Name list box.
3.
Select the output format for the transformation from the Target Format list box.
4.
Enter a rendition description, if desired.
5.
Set this transformation as the default proxy, if desired, by choosing the Yes option.
6.
Save this transformation, if desired, by choosing the Yes option.
Consult the Documentum Process Builder User Guide for further instructions on how to use the workflow feature.
Using the CTS Reporting Tool The 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 and can assist with load balancing strategies. Reporting can be logged for a configurable time frame and then rolled over to be archived. The resulting information is retained in the repository and is viewable as a CSV formatted file (a report format using comma-separated values) through Digital Asset Manager (DAM). Users can view their own CTS reporting data. Administrators have access to all data. Usage tracking is configured in Documentum Administrator. The CTS Reporting Tool reports on the number of requests in a given time frame according to the following options:
44
EMC Documentum XML Transformation Services Version 6 Administration Guide
Administering XML Transformation Services
•
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 or off.
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:
4.
5.
•
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 be archived.
If you have enabled Reporting Configuration and Archiving Configuration, provide the 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 archived and for the compilation to start again.
•
(Archiving monitor interval in seconds) Archiving Monitor Interval, to set the length of time in seconds the report should be updated.
Click OK.
Viewing the CTS Reporting Tool report When the CTS Reporting Tool is enabled, the following information is recorded for each transformation request:
EMC Documentum XML Transformation Services Version 6 Administration Guide
45
Administering XML Transformation Services
•
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 the following fields: •
Report name
•
Start date
•
End date
3.
Click OK.
4.
The Select Folder screen appears. Select the destination folder to save the retrieved report. Click OK. A CSV report opens with the requested information.
Managing the transformation queue The Queue Management feature provides a mechanism for monitoring and administrating transformation request queues. This feature allows users to view or delete their own pending transformation requests. Administrators can manage the queues for all users and change the priority of transformation requests when required.
46
EMC Documentum XML Transformation Services Version 6 Administration Guide
Administering XML Transformation Services
The Queue Management feature is accessed through the Transformation node in XML Transformation Services via Digital Asset Manager (DAM). Administrators can manage the queue by deleting items or changing the priority of items. Users can view their own transformation requests and delete their own transformation requests, but cannot change a queue item priority. •
Viewing transformation requests in the queue, page 47
•
Changing a queue item’s priority, page 48
•
Viewing details of a queue item, page 48
•
Deleting a pending queue item, page 49
•
Configuring additional queue management fields, page 50
•
Removing a queue management field, page 50
Viewing transformation requests in the queue Users can monitor the status of their transformation requests by viewing the queue. If a user is dissatisfied with the priority level of their transformation request(s), they can ask their 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 current queue items. Transformation requests are displayed in priority order. The priority level of an item is indicated as follows:
3.
4.
•
denotes a high priority item
•
denotes a medium priority item.
•
denotes a low priority item.
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.
To sort transformation requests in ascending or descending order, click the header field on each of the columns.
EMC Documentum XML Transformation Services Version 6 Administration Guide
47
Administering XML Transformation Services
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 the transformation queue by selecting the Transformations node. The transformation queue 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 higher the 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 the queue position has changed. The color code of the priority item should change to a higher priority. See Viewing transformation requests in the queue, page 47 for queue item priority level color codes.
Viewing details of a queue item When a pending item is in the queue, the following transformation details are available depending on which fields are configured:
48
•
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 be a 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.
EMC Documentum XML Transformation Services Version 6 Administration Guide
Administering XML Transformation Services
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 the transformation queue by selecting the Transformations node. The transformation queue 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 own queue items. The deletion is not immediate for users. Items are marked, then polled and 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:
3.
•
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.
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 items using 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 transformation queue. If the queue item is being processed, an error will show saying "Transformation request is being processed, can’t delete."
EMC Documentum XML Transformation Services Version 6 Administration Guide
49
Administering XML Transformation Services
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 and the default column setting on the right.
4.
Select an additional item from the left list "Select attributes to display". Click the button to add to the right list "Selected attributes to display as column". The right list shows 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 and the default column setting on the right.
4.
Select an item from the right list "Selected attributes to display as column". Click button to move it to the left list "Select attributes to display". The right list shows the new attribute removed. Click OK. The list view appears.
50
EMC Documentum XML Transformation Services Version 6 Administration Guide
Administering XML Transformation Services
5.
Verify that the list view has one less column.
EMC Documentum XML Transformation Services Version 6 Administration Guide
51
Administering XML Transformation Services
52
EMC Documentum XML Transformation Services Version 6 Administration Guide
Chapter 4 Working with Proles
The predefined profiles in XML Transformation Services cover most of the common document transformations, such as XML to PDF and XML to HTML. XML Transformation Services enables the system 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 a profile will customize it to your specifications.
Understanding command-line les Command-line files are stored in the repository as XML files that can be used by the transformation profiles as needed. The command-line file contains detailed instructions for the plug-in. The XML Transformation Server distinguishes between DITA and DocBook source files through the input_doctype_family name token in the plug-in configuration file. The command-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 could be controlled at the command level. Command-line files are specific to each plug-in, since their capabilities vary. Each profile contains the profile name, a label (the text that displays in the client application), a description, required attributes, and supported source/target dm_format objects. Profiles for which all parameters are defined contain only the name, label, description, and supported source and target formats. Each profile is linked to either the DITA or DocBook command-line file.
EMC Documentum XML Transformation Services Version 6 Administration Guide
53
Working with Proles
Building and modifying proles with Prole Editor The Profile Editor assists with editing or building new profiles. New or existing profiles can be customized by editing default values and adding or removing formats. Users can select multiple profiles to create chained or parallel profiles that automate a series of transformations. 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 the order 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.0. See XML Transformation Services Release Notes for further information. This section contains the following procedures: •
Editing a profile, page 54
•
Building a new profile, page 55
•
Building a chain profile, page 57
•
Building a parallel profile, page 59
The following procedure describes how to edit a profile in a repository using the Profile Editor
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 change the 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.
54
On the Info tab, edit the name, label, and description of the profile, if required. •
Click Webtop Enabled, if required.
•
Click Browse to edit the folder destination, if required.
EMC Documentum XML Transformation Services Version 6 Administration Guide
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 Services to 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 the edited 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 the previous screens. Click Finish to validate and save the new profile.
10. The Profiles page is displayed. Verify that the edited profile appears on the Profiles page. 11. All profile changes require that you stop and restart the Content Transformation Services service (see Starting and stopping XML Transformation Services, page 39) 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.
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 change the view to all profiles. A list of profiles appears.
EMC Documentum XML Transformation Services Version 6 Administration Guide
55
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. •
Click Webtop 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 Services to 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 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 adjusted parameter.
Click Next. The Summary screen appears. 8.
The Summary screen confirms the elements that were selected and defined in the previous screens. Click Finish to validate and save the new profile.
9.
The Profiles page is displayed. Verify that the new profile appears on the Profiles page.
10. All profile changes require that you stop and restart the Content Transformation Services service (see Starting and stopping XML Transformation Services, page 39) on the XML Transformation Services host.
56
EMC Documentum XML Transformation Services Version 6 Administration Guide
Working with Proles
Building a chain prole Chaining profiles invoke each profile within them in stages. Transformations also occur one at a time, one transformation is required for the next transformation. The result of a chaining profile would be the output of the last profile in the chain. A chained profile creates one output file. The following procedure describes how to create a chained transformation according to your specific requirements.
To build a chain 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 change the view to all profiles. A list of profiles appears.
4.
From the list, select the profiles with which you will build the new profile. Select Tools->Build Profile>Chain.
5.
The Info tab will display. •
Enter the generic name, label, and description of the new profile.
•
Click Webtop 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 Profiles list box. The right list shows the new product(s) added. OR
•
Select the inner profile(s) from the Selected Profiles list. Use the directional arrow, to move the selection(s) to the Available Profiles lists. The right list shows the new product(s) added.
•
Use the up and down directional arrow to rearrange the Selected Profiles list to create 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. To configure a path: •
Select a path
EMC Documentum XML Transformation Services Version 6 Administration Guide
57
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 Services to generate default renditions for that profile. Select the profile’s new source and target 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 the chain 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 chained profile. Click Finish to validate and save the new profile. 11. The Profiles page is displayed. Verify that the new profile appears on the Profiles page. 12. All profile changes require that you stop and restart the Content Transformation Services service (see Starting and stopping XML Transformation Services, page 39) on the XML Transformation Services host.
58
EMC Documentum XML Transformation Services Version 6 Administration Guide
Working with Proles
Building a parallel prole The following procedure describes how to create a parallel transformation according to your specific requirements. Parallel profiles specify a list of profiles that are executed one after another or at the same time. For each profile in the parallel profile, you can specify whether the next profile should 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. Each profile does not have to be complete before the next profile starts. The result of parallel profiles 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.
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 change the view to all profiles. A list of profiles appears.
4.
From the list, select the profiles with which you will build the new profile. Select Tools->Build Profile>Parallel. The Info tab will display. •
Enter the generic name, label, and description of the new profile.
•
Click Webtop 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 Profiles list box. The right list shows the new product(s) added. OR
•
Select the inner profile(s) from the Selected Profiles list. Use the directional arrow, to move the selection(s) to the Available Profiles lists. The right list shows the new product(s) added.
•
Use the up and down directional arrow to rearrange the Selected Profiles list to create 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:
EMC Documentum XML Transformation Services Version 6 Administration Guide
59
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 Services to generate default renditions for that profile. Select the profile’s new source and target 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 the chain 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 parallel profile. Click Finish to validate and save the new profile.
10. The Profiles page is displayed. Verify that the new profile appears on the Profiles page. 11. All profile changes require that you stop and restart the Content Transformation Services service (see Starting and stopping XML Transformation Services, page 39) on the XML Transformation Services host.
60
EMC Documentum XML Transformation Services Version 6 Administration Guide
Working with Proles
Modifying proles manually This section describes how to modify a system profile manually. You can modify a profile if the current profile is unsuitable for your needs. Modifying a profile will customize it to your specifications. XML Transformation Server updates all dm_media_profile objects on startup. It removes all repeating SOURCE and TARGET attributes and resets them. Therefore, when a user modifies a dm_media_profile object, XML Transformation Server automatically updates the 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. Note: If these files are not immediately visible, select Show All Objects and Versions from the Show list box.
4.
Check in the profile.
5.
If the profile was part of a chain or sequence, then you must stop and restart the Content Transformation Services service (see Starting and stopping XML Transformation Services, page 39) on the XML Transformation Services host.
Using DQL in proles Document Query Language (DQL) can be specified for all XML Transformation Services profile files. Through DQL, default profile parameters can be supplied. The DQL is presented as an attribute of the Parameter node of profiles (named dql). This section discusses: •
The dql attribute value syntax, page 62
•
DQL guidelines, page 62
•
DQL query examples, page 62
•
Querying the r_object_id attribute, page 63
EMC Documentum XML Transformation Services Version 6 Administration Guide
61
Working with Proles
The dql attribute value syntax The syntax for the dql profile parameter attribute value does not differ from a regular DQL statement. It supports the following tokens (placeholders) which are recognized by the system: •
[sysobject_id_token]: placeholder for a Sys Object ID (the r_object_id attribute for dm_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 sys object 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 is correctly supplied in profile. The system replaces the contained placeholders with runtime values, and then executes it against the repository.
•
Upon executing the query, the system will just consider the first row returned in the result set. If the query is set to return multiple records, just the first one will be considered.
•
All the attribute values returned will be formatted accordingly, based on the attribute type (such as date, string, or Boolean).
DQL query examples Complex queries can be created with DQL. Queries can include all four supported tokens, as many times as they are needed. The following examples illustrate how to supply the DQL for the dql profile parameter attribute:
The following query can be used for getting the current lifecycle state for a sys object, as string:
For getting information that is pertinent to the user who executes the profile, the user keyword can be used in query:
Querying the r_object_id attribute Having the r_object_id attribute as part of the SELECT clause of the query will not result in having the actual Object ID value supplied as part of the default parameter value. This attribute sometimes has a special (system) role in query (for example, properly returning the repeating attributes in a single row). The system cannot process its real purpose at runtime, and therefore will not consider it when building the profile parameter default value. In order to have the Object ID value supplied as part of the profile default parameter value, syntax must be provided that will use the [sysobject_id_token] placeholder on the query’s SELECT clause, as follows:
EMC Documentum XML Transformation Services Version 6 Administration Guide
63
Working with Proles
64
EMC Documentum XML Transformation Services Version 6 Administration Guide
Chapter 5 Performing Transformations
XML Transformation Services offers various transformation options to users. This chapter provides basic procedural information for performing these transformations. As with all Content Transformation Services products, the capabilities of XML Transformation Services are accessed through Digital Asset Manager, a Documentum client application. To perform these transformations, log in to the repository serviced by XML Transformation Services. The user transformations available with XML Transformation Services are explained in the following sections: •
Transforming DITA files, page 65
•
Transforming DocBook files, page 67
Transformations that create new renditions occur on one item at a time and requests are processed asynchronously, meaning that new renditions may not be available immediately. You receive a notification in your Inbox when a transformation is completed or if a transformation fails. Viewing renditions, page 72 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 document chosen for transformation. For example, if a DITA source file is selected, DocBook profiles are not available.
Transforming DITA les Transformation of DITA compliant XML files to PDF, HTM, or ZIP are handled by one profile. Users select the output format and content filters 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 The Select Transformation tab appears displaying the selected file and the available transformations for the selected file.
EMC Documentum XML Transformation Services Version 6 Administration Guide
65
Performing Transformations
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 Operating System Filter box lists filters that have likely been customized by your organization and will vary according to your organization’s requirements. Note: For all DITA transformations, you choose the filter parameters you wish to exclude. For example, to filter the content based on operating systems, select all of the operating systems that do not apply.
5.
•
Select the document version types from the Revision Filter listbox that you wish to exclude.
•
Select the audience level filter from the Audience Filter listbox that you wish to exclude.
•
Enter a product filter type in the Product Filter field box, if required.
•
Click Next. The Save As screen appears.
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 own workflow, 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 it is versioned. Click Finish. 7.
66
If you selected Create a New Object, the New Object Definition screen appears. Enter a 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.
EMC Documentum XML Transformation Services Version 6 Administration Guide
Performing Transformations
•
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.
Note: A format must be richmedia_enabled to allow for transformation whenever it is versioned. Click Finish 8.
The transformation request is immediately sent to the appropriate queue for processing.
Transforming DocBook les There are three profiles available for transforming DocBook source files. Each profile transforms 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). Users can 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 available transformations 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 Draft Watermark •
Select one of the options from the Set Draft Watermark listbox.
•
Select the display parameter from the Display Comments listbox.
EMC Documentum XML Transformation Services Version 6 Administration Guide
67
Performing Transformations
5. 6.
•
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 your organization, 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.
Click Next. The Save As screen appears. 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 own workflow, create a translation of it, apply its own permission, and so on.
7.
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 it is versioned. Click Finish. 8.
68
If you selected Create a New Object, the New Object Definition screen appears. Enter a 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 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.
EMC Documentum XML Transformation Services Version 6 Administration Guide
Performing Transformations
Note: A format must be richmedia_enabled to allow for transformation whenever it is versioned. Click Finish 9.
The transformation request is immediately sent to the appropriate queue for processing.
Transforming DocBook les to HTML Users can select from a variety of options for customizing HTML output, including the 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 Formats The Select Transformation tab appears displaying the selected file and the available transformations for the selected file.
3.
Select DocBook HTML Transform option. Click Next. The Transformation Details tab appears.
4.
5.
Enable the following options as appropriate: •
Set Draft Watermark
•
Display Comments
•
Create New HTML Files Down to Section Level (which determines the chunking depth)
Choose the appropriate filters for this transformation. The filters that appear have likely been customized by your organization, and will vary according to your organization’s requirements. Note: For all DITA transformations, you choose the filter parameters you wish to exclude. For example, to filter the content based on operating systems, select all of the operating systems that do not apply. 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 own workflow, create a translation of it, apply its own permission, etc.
EMC Documentum XML Transformation Services Version 6 Administration Guide
69
Performing Transformations
7.
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 it is versioned. Click Finish. 8.
If you selected Create a New Object, the New Object Definition screen appears. Enter a 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.
Note: A format must be richmedia_enabled to allow for transformation whenever it is versioned. Click Finish 9.
The transformation request is immediately sent to the appropriate queue for processing.
Transforming DocBook les to PDF Users can customize the output PDF by choosing from various output options such as paper 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 Formats The Select Transformation tab appears displaying the selected file and the available transformations for the selected file.
3.
70
Select Transform DocBook to PDF option. Click Next.
EMC Documentum XML Transformation Services Version 6 Administration Guide
Performing Transformations
The Transformation Details tab appears. 4.
5.
Enable the following options as appropriate: •
Set Draft Watermark
•
Display Comments
•
Paper Type
•
Render for Double-Sided Printing
•
Page Orientation
Choose the appropriate filters for this transformation. The filters that appear have likely been customized by your organization, and will vary according to your organization’s requirements. Note: For all DITA transformations, you choose the filter parameters you wish to exclude. For example, to filter the content based on operating systems, select all of the operating systems that do not apply. 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 own workflow, create a translation of it, apply its own permission, etc.
7.
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 it is versioned. Click Finish. 8.
If you selected Create a New Object, the New Object Definition screen appears. Enter a 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.
EMC Documentum XML Transformation Services Version 6 Administration Guide
71
Performing Transformations
•
Click Save Transformation if you wish to apply this transformation every time the parent object is versioned.
Note: A format must be richmedia_enabled to allow for transformation whenever it is versioned. Click Finish 9.
The transformation request is immediately sent to the appropriate queue for processing.
Viewing renditions When transformation requests are completed, the renditions are stored in the repository with 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 error will occur.
72
EMC Documentum XML Transformation Services Version 6 Administration Guide
Chapter 6 Troubleshooting
This chapter provides troubleshooting information for errors encountered from various elements of XML Transformation Services. Also see XML Transformation Services Release Notes, which contain additional information regarding limitations, technical notes, usability, and known bugs. This section contains troubleshooting guidance relating to: •
Error events and log files, page 73
•
A transformation request fails, page 74
•
A profile error occurs, page 74
•
XML Transformation Server cannot add a rendition to a particular format, page 75
•
XML Transformation Server cannot log in to the repository, page 75
•
CTS Administration Agent gives AGENT_INACCESSIBLE message, page 76
•
Content Transformation Services fails to function, page 77
Error events and log les Any time XML Transformation Server fails to process a particular item, it queues an event (dm_autorender_error or dm_mediaserver_error) to the Inbox of the repository user defined as the system operator in the XML Transformation Server configuration file. The first step in troubleshooting XML Transformation Server is to check the system operator’s Inbox for any messages that might explain the error. Additionally, review the CTS_log.txt log file. This log file contains errors and exceptions that are specific to XML Transformation Server. It is located on the XML Transformation Server host, in this directory: C:\Program Files\Documentum\CTS\config\logs
EMC Documentum XML Transformation Services Version 6 Administration Guide
73
Troubleshooting
A transformation request fails Occasionally, a transformation request may fail to process, or may process incorrectly. In most cases, the error messages will indicate the problem. Notification of a transformation failure will be sent to the system operator’s Inbox. The following actions can be performed to determine the cause of a transformation request failure.
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 format of 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 may not be supported by XML Transformation Services.
3.
Check that disk space and memory on the XML Transformation Server host is sufficient 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 occurs Errors related to profiles may occur. For example, if a profile was edited and updated manually, there may be issues with the XML file. There are a number of ways to determine the cause of a profile error, as described in the 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 in C:\Documentum\config), for exceptions.
3.
If you suspect the profile itself is the cause of the error, log into either a Documentum Client (such as Webtop or Digital Asset Manager) as an administrator user or log in to Documentum Administrator. Make sure that there are three folders in the repository for XML Transformation Server profiles: •
74
/System/Media Server/Profiles
EMC Documentum XML Transformation Services Version 6 Administration Guide
Troubleshooting
•
/System/Media Server/System Profiles
•
/System/Media Server/Command Line Profiles
These 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_profile object) exists in the appropriate folder (listed above) and that the name in the profile is identical to the actual file name. For more information on where profile files should be located, see Modifying profiles manually, page 61.
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 a rendition to a particular format If XML Transformation Server cannot add a rendition to a particular format, first check the Inbox of the XML Transformation Server system operator for error messages, and then 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 object was deleted from the repository before the XML Transformation Server could add a rendition to it.
XML Transformation Server cannot log in to the repository XML Transformation Server connects to the repository using a repository SuperUser account. If XML Transformation Server cannot log in to the repository, ensure that a valid repository SuperUser is identified for XML Transformation Server to use.
To identify the cause of XML Transformation Server not logging in to the repository: 1.
Make sure that the repository is running.
2.
Check your network connections.
3.
Check that the Connection Broker is running.
EMC Documentum XML Transformation Services Version 6 Administration Guide
75
Troubleshooting
4.
Check that the dfc.properties file points to the Connection Broker that recognizes your 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 the XML Transformation Server element.
9.
Make sure you have configured the SessionService.xml file to the proper user in the repository who has SuperUser access. If necessary, check with the repository administrator 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 gives AGENT_INACCESSIBLE message If the CTS Administration node in Documentum Administrator (DA) is showing an AGENT_INACCESSIBLE message, it indicates that DA was unable to connect to the agent. 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 called Documentum 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 the agent. If this service is running, you should be able to ping the agent by opening your browser and pointing it to http://machinename:/CTSAgent/CTSAgent (the default port is 9095). It should respond with a page saying "Content Transformation Services Agent" if it is running. If the Admin Agent is not running, see Starting and stopping the CTS Administration Agent, page 38 to start the CTS Admin Agent.
76
EMC Documentum XML Transformation Services Version 6 Administration Guide
Troubleshooting
3.
The server method on the Content Server is not there. You can look for the server method using Documentum Administrator (Administration > Job Management > 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 to function Content Transformation Services fails to function and you receive an error message when attempting transformations. The error may occur if the Global Registry does not have a Content Transformation Services product (Rich_Media_Services and Transformation docapps) configured against it. The Global Registry is a common repository where commonly used docapps are installed. Ensure Rich_Media_Services and Transformation docapps are run against the Global Registry repository. See instructions in the XML Transformation Services Installation Guide.
EMC Documentum XML Transformation Services Version 6 Administration Guide
77
Troubleshooting
78
EMC Documentum XML Transformation Services Version 6 Administration Guide
Index
A adding plug-ins, 12 repositories, 23 admin password, changing, 40 architecture, 11
B batch files, 22
C Can Be Indexed setting, 25 changing configuration, 39 checked out documents, 13 to 15 CHM renditions, 10, 15 to 16 COM Class ID for format, 24 command-line files, 74 storing, 53 Compiled HTML Help, see CHM renditions configuring queue item sign-off, 41 configuring XML Transformation Server changing login user name, 22 changing the logging level, 22 changing the maximum number of queue items, 22 changing the notification setting, 22 changing the polling interval, 22 changing the queue item expiry, 22 changing the system operator, 22 configuring XML Transformation Services changing the repository, 23 Configurator, 23 using Documentum Administrator, 23 Content Transformation Monitor Services, 39 Content Transformation Services
description, 9 error message, 77 fails to function, 77 format awareness, 10 queue, 10 scalability, 10 Create New Template command, 25 creating CHM renditions, 15 HTML renditions, 14 PDF renditions, 13 CTS Activity Template document transformation, 44 Documentum Process Builder, 42 transformation profiles, 43 users, 42 workflow parameters, 43 working with, 42 CTS Admin Agent, 22 CTS Reporting Tool, 44 disable, 45 enable, 44 viewing reports, 45 CTS Service, changing user, 40
D DAM modifying transformation profiles, 54 to 55, 57, 59 using DFC, 12 details of a CTS instance, viewing, 38 DFC about, 12 installing with XML Transformation Services, 12 Digital Asset Manager, see DAM DITA filters adding new, 29 configuring, 28 DITA source files
EMC Documentum XML Transformation Services Version 6 Administration Guide
79
Index
transforming, 65 DITA, transform handler, 13 dita_transform_chm.xml, configuring, 31 dita_transform_command.xml file, 30 dita_transform_pdf.xml, configuring, 31 dita_transform.xml adding filters to, 29 dita_transform.xml, configuring, 28 dm_media_profile object, 61 dm_mediaserver_error, 73 dm_queue, 14, 16 DocBook filters adding new, 32 configuring, 31 DocBook source files transforming to CHM, 67 transforming to HTML, 69 transforming to PDF, 70 DocBook transform handler, 13 docbook_transform_command.xml file, 33 docbook_transform.xml adding filters to, 32 Documentum Administrator accessing the configuration screen, 23 Create New Format Object page, 24 defining file formats, 24 Documentum Foundation Classes, see DFC DOS file formats, defining, 25 DQL guidelines, 62 in profiles, 61 query examples, 62 r_object_id attribute, 63 syntax, 62 tips, 62
E errors, 73 to 75 dm_mediaserver_error, 22 in log files, 38 receiving, 22 events, 73 dm_mediaserver_error, 22
F file formats, 24
80
creating templates, 25 supported as source for CHM, 18 supported as source for HTML, 18 supported as source for PDF, 18 filename extensions, 24 filters adding product names, 27 default, 26 definition, 26 for DITA transformations, 28, 66, 69, 71 for DocBook transformations, 31 in source files, 26 format_token, 62 FormatMapperService, updating, 25
G Global Registry CTS product, 77
H HTML renditions, 10, 14 to 15 HyperText Markup Language, see HTML renditions
I ignoreItemsToSignOffLimit, 41 Inbox notifications, 22, 73 to 74 changing in DA, 22 configuring, 33 settings, 33 Index with Filter setting, 25 with Rendition setting, 25 input_doctype_family name, 53 installation plug-ins, 12 scalability, 10 typical, 11 instance details, viewing, 38
L load balancing, 40 locked documents, 13 to 15 log files, 73 viewing, 38 logging level, 40
EMC Documentum XML Transformation Services Version 6 Administration Guide
Index
changing, 22 login, 75 login user, identifying, 22
M Macintosh Creator format setting, 25 Macintosh Type format setting, 25 markerInterval, 41 Media_Server_Log.txt, 73 MIME type, 24 modifying system profiles, 54 modifying system profiles, 61 modifying transformation profiles, 61 monitor services, 39 multiple servers, 40
profile_audience filter, 26 profile_os filter, 26 profile_product filter, 26 adding names to, 27 profile_revision filter, 26 profiles, 74 modifying, 54, 61 using DQL, 61 ProfileSchema.dtd file, 27 to 28
Q
notifications changing in DA, 22 configuring, 33
queue objects, 11 removing unsupported formats from, 10 queue items changing the expiry, 22 changing the maximum number allowed, 22 configuring sign-off, 41 queue marker mechanism, 41 queue, managing, 46
O
R
objects, 14 to 16 dm_media_profile, 61
r_object_id, 63 refreshing XML Transformation Services, 38 registry ID for format, 24 removing a repository, 23 renditions, 75 viewing, 72 repository, 75 adding, 23 changing, 23
N
P page_modifier_token, 62 page_token, 62 password, changing, 38, 40 PDF renditions, 13 to 15 placeholders, 62 plug-ins adding, 12 description, 12 installation of, 12 standard, 12 using command-line files, 53 polling interval, changing, 22 Portable Document Format, see PDF renditions Profile Editor build profile, 55, 57, 59 chain profile, 55, 57, 59 modifying profiles, 55, 57, 59 sequence profile, 55, 57, 59 specialized profile, 55, 57, 59
S scalability of Content Transformation Services, 10 servers, multiple, 40 setPassword utility, 40 settings Can Be Indexed, 25 Default File Extension, 24 Index with Filter, 25 Index with Rendition, 25 MIME type, 24 source formats supported, 18
EMC Documentum XML Transformation Services Version 6 Administration Guide
81
Index
starting XML Transformation Services, 38 to 39 stopping XML Transformation Services, 38 to 39 sysobject_id_token, 62 system architecture, 11 system operator user, identifying, 22 system profiles, modifying, 54, 61
T tokens, 62 Transform DocBook to HTML.xml, configuring, 31 transform handlers, 13 Transformation node, 46 transformation profiles, 74 command-line files, 53 transformation queue, 46 Transformation queue changing queue priority, 48 configuring queue management fields, 50 deleting queue item, 49 removing queue management field, 50 viewing details of queue item, 48 viewing transformations, 47 Transformation Services extending, 12 requirements, 12 role in XML Transformation Services, 11 transformations, 74 DITA source files, 65 DocBook source files, 67 performing, 11, 65
82
viewing completed, 72 troubleshooting, 73 to 74 with log files, 38
U user transformations, 65 users, changing for CTS Service, 40 for repository login, 22 system operator, 22
W WDK, relation to XML Transformation Services, 12 Web Development Kit, see WDK Windows Service, 10
X XML Transformation Server, 73 position in installation, 11 XML Transformation Services architecture, 11 changing settings, 39 Configurator, 23 description, 10 environment, 11 features, 17 refreshing, 38 starting, 38 to 39 stopping, 38 to 39
Z Zip files, 15 to 16 ZIP renditions, 10
EMC Documentum XML Transformation Services Version 6 Administration Guide
