Documentum Content Distribution Services TM Administration Guide

Transcription

1 Documentum Content Distribution Services TM Administration Guide Version 5.3 SP5 August 2007

2 Copyright EMC Corporation. All rights reserved.

3 Table of Contents Preface... 7 Chapter 1 Introducing Documentum Content Distribution Services... 9 Understanding content distribution Making content available: offers and packages Preparing content for delivery: Templates Receiving content: subscribers and subscriptions Scheduling delivery Understanding the CDS Server What the CDS Server does? What the CDS Server retrieves from the repository? What the CDS Server delivers to subscribers? Using CDS Administrator tasks Subscriber tasks Chapter 2 Using CDS Administrator Logging in Navigating in the application Using list pages Using attributes pages Using selection pages Scheduling offers and subscriptions Deleting schedules Sending notifications Chapter 3 Offering Content Before you begin Creating offers Specifying the offer query Creating templates Chapter 4 Registering subscribers Creating subscriber user accounts Creating groups Chapter 5 Subscribing to Offers Before you begin Creating subscriptions Chapter 6 Using the Content Distribution Services Client Application Logging in Documentum Content Distribution ServicesTM Administration Guide 3

4 Table of Contents Configuring subscriptions Reading notifications Chapter 7 Monitoring Server Processing Reading the CDS Server log files Configuring the CDS Server Modifying notification messages Managing content cache storage Resolving delivery issues Modified offers and subscriptions Retrieving content by reference Modifying templates Appendix A Content Distribution Services Custom JSP Tag Reference applyformat formatdate formatnumber replacetext stripimages striptables striptags track truncatetext writedocument Appendix B Attribute File XML Format Documentum Content Distribution ServicesTM Administration Guide

5 Table of Contents List of Figures Figure 1 1. Basic Documentum Content Distribution Services architecture Figure 1 2. Offers and packages Figure 1 3. Applying templates to offer content Figure 1 4. Subscriber access to offers Figure 1 5. Server scheduling Figure 2 1. Parts of the CDS Administrator screen Figure 2 2. List Page Figure 2 3. Attributes page Figure 2 4. Selection page Figure 2 5. Schedule page Figure 2 6. Schedule property page Documentum Content Distribution ServicesTM Administration Guide 5

6 Table of Contents List of Tables Table 7 1. Commonly updated cxflog.xml settings Table 7 2. Commonly updated cds.xml settings Table A 1. Content Distribution Services JSP Tags Documentum Content Distribution ServicesTM Administration Guide

7 Preface This manual provides system administrators with the information necessary to implement an automated distribution network using Documentum Content Distribution Services (CDS). It provides an overview of the concepts of distribution, the architecture of the Documentum solution, and detailed instructions for creating the necessary objects. The manual also covers the CDS Client, which is software that distributors can provide to their subscribers. Intended audience This manual is intended primarily for system administrators who need to set up the Content Distribution Services Server and maintain the system. It also includes information that is relevant for subscribers who want to receive the content distributed by the CDS Server. Revision history The following changes have been made to this document. Revision history Revision date August 2007 Description Initial publication Documentum Content Distribution ServicesTM Administration Guide 7

8 Preface 8 Documentum Content Distribution ServicesTM Administration Guide

9 Introducing Documentum Content Distribution Services Chapter 1 Documentum Content Distribution Services provides a framework for distributing content to people both inside and outside of your company s firewall. People subscribe to the content you offer, much as they subscribe to magazines. With this product, you can automatically inform interested parties about updates to a repository and forward them the new or the updated documents. The prototype example of content distribution is a news feed. When a news service posts a story, or an industry analyst updates a research report, or a corporation issues a press release, there are a number of people who want to receive the document. Content Distribution Services enables the distributor to maintain a list of subscribers who are interested in receiving updates and to forward them the updates automatically. A common business scenario for Content Distribution Services is distributing up-to-the-minute information about your company s products and services to partners and customers. For example, suppose your partners maintain a version of your product catalog on their web sites. Content Distribution Services enables you to distribute updates to the catalog and enables the partners to automatically incorporate the updates on their sites. Content Distribution Services delivers content using standard internet protocols, which means that subscribers need not be part of the same company network as the distributor nor have access to secure areas of the distributor s network. This chapter provides an overview of content distribution, both the basic concepts and the architecture of Documentum Content Distribution Services. The major sections are: Understanding content distribution, page 10 Understanding the CDS Server, page 16 Using CDS, page 20 Documentum Content Distribution ServicesTM Administration Guide 9

10 Introducing Documentum Content Distribution Services Understanding content distribution Documentum Content Distribution Services has two major components: a Content Distribution Services server (CDS Server) and multiple subscribers. The CDS Server monitors one or more content repositories for updates, packages the new or updated content, and distributes it to subscribers. The server also manages the list of subscribers: their privileges, which content each subscriber is interested in, and how and where to deliver the updates. The subscriber accepts content packages from the CDS Server and updates its local content repository as appropriate. 10 Documentum Content Distribution ServicesTM Administration Guide

11 Introducing Documentum Content Distribution Services Figure 1-1. Basic Documentum Content Distribution Services architecture A CDS Server serves any number of subscribers. The server can offer content from Documentum repositories or Site Caching Services repositories, from relational databases, or from file-based repositories. Subscribers can receive content using one of three delivery protocols: Information and Content Exchange (ICE), an industry-standard message protocol for content distribution File Transfer Protocol (FTP), the internet standard for simple file transfers using internet standard Simple Mail Transfer Protocol (SMTP) Documentum Content Distribution ServicesTM Administration Guide 11

12 Introducing Documentum Content Distribution Services The protocols are listed in descending order of sophistication. ICE subscribers have software that coordinates the exchange with the CDS Server and writes the delivered content to the target repository. For FTP subscribers, the CDS Server writes the content directly to the target repository using the FTP protocol. subscribers receive the content through their software and must develop their own way of transferring the content from the message to the repository. Documentum Content Distribution Services includes ICE-compliant CDS Client software that a distributor can distribute to its subscribers. However, subscribers need not use the CDS Client software to receive the content through FTP or . The Documentum Content Distribution Services Release Notes contains details about the system requirements. The following sections provide an overview of the key tasks involved in distributing content and introduce the Content Distribution Services object types involved in the tasks: Making content available: offers and packages, page 12 Preparing content for delivery: Templates, page 13 Receiving content: subscribers and subscriptions, page 14 Scheduling delivery, page 15 Making content available: offers and packages To make content available to subscribers, a distributor defines offers. An offer is a collection of documents for distribution. The offer consists of a query that retrieves the relevant documents from the source repository and a schedule for when the CDS Server runs the query. For the first time, when the CDS Server runs the offer query, it creates a package consisting of all the documents returned by that query. The package represents the contents of the offer at a particular time and is the object that the server actually delivers to subscribers. Each subsequent time that the server runs the offer, it compares the results to the previous package and creates a new package consisting of just the updates. The server keeps track of which package each subscriber last received. Each time it runs the subscription, the server creates a delivery package consisting of only the changes to the offer since the last delivery; that is, it delivers the cumulative content of the new packages. The Chapter 3, Offering Content contains more information on creating offers. 12 Documentum Content Distribution ServicesTM Administration Guide

13 Introducing Documentum Content Distribution Services Figure 1-2. Offers and packages Preparing content for delivery: Templates When the CDS Server creates an offer package, the content and format of each document in the package is the same as it is in the source repository. The content distributor may want to modify or enhance the content before delivering it to subscribers. For example, they might add a header to each document with their company logo or a date stamp. Content Distribution Services enable you to modify the content of an offer using templates. A template contains instructions for manipulating offer content, which the CDS Server performs before sending the content to a subscriber. Content Distribution Services support three types of templates: JavaServer Page (JSP) templates that process document content, such as by adding information or modifying the format XSL stylesheets that process the content of XML documents Documentum Content Distribution ServicesTM Administration Guide 13

14 Introducing Documentum Content Distribution Services ZIP templates that create compressed versions of the documents The CDS Server can apply templates to each document individually, to all documents in an offer package collectively, or to a subscription package as a whole. Most commonly, JSP and XML templates apply to each document individually and ZIP templates apply to the offer or subscription package. The Creating templates, page 52 contains more information on creating templates. When you define an offer, you specify which templates are available for that offer. When a subscriber creates a subscription, he or she can choose whether to apply one or more of the available templates. The Chapter 3, Offering Content and Chapter 5, Subscribing to Offers contain more information. Figure 1-3. Applying templates to offer content Receiving content: subscribers and subscriptions To receive content from a CDS Server, a person must be registered on the server as a subscriber. The subscriber user account identifies which offers are available to the subscriber. 14 Documentum Content Distribution ServicesTM Administration Guide

15 Introducing Documentum Content Distribution Services Figure 1-4. Subscriber access to offers Once subscribers have accounts on the CDS Server, they can subscribe to any offers linked to their accounts. To actually receive the contents of an offer, the subscriber creates a subscription (or the content provider creates a subscription on behalf of that subscriber). With a subscription, the subscriber signs up for one or more offers as they exists now and for any subsequent updates. The subscription specifies: Which offers the subscriber is subscribing to Which of the available protocols to use for delivering the content (ICE, FTP, or ) Where to send the content How often to check for updates to the offers; that is, when to check for new packages When the CDS Server runs the subscription, it delivers the content of the latest packages to the address in the subscription, using the specified protocol. The subscriber updates the target repository. The Chapter 4, Registering subscribers contains more information on creating user accounts for subscribers. The Chapter 5, Subscribing to Offers contains more information on creating subscriptions. Scheduling delivery Each offer and each subscription has a schedule associated with it. These schedules are independent of each other. For example, suppose an offer runs every four hours, and a subscription to that offer runs twice a day (every 12 hours). The server may create as many as three new packages between sending updates to the subscriber. When the subscription runs, the server delivers to the subscriber the content of all packages created since the last time the subscription ran. Documentum Content Distribution ServicesTM Administration Guide 15

16 Introducing Documentum Content Distribution Services Figure 1-5. Server scheduling Understanding the CDS Server This section gives an overview of how the CDS Server distributes content based on the elements described in the previous sections. It provides a more technically oriented view of: What the CDS Server does?, page 17 What the CDS Server retrieves from the repository?, page 18 What the CDS Server delivers to subscribers?, page Documentum Content Distribution ServicesTM Administration Guide

17 Introducing Documentum Content Distribution Services What the CDS Server does? Once you have created and scheduled offers and subscriptions, the CDS Server manages content distribution automatically. When the CDS Server is running, it monitors its internal schedule to determine when to run offers and subscriptions. When the time comes to run an offer, the server performs these steps: 1. Checks that the offer is active. 2. Connects to the source repository defined for the offer. 3. Submits the selection query defined for the offer. 4. Receives the results back from the source repository. 5. Compares the returned results to the current state of the offer. 6. If necessary, creates a new package reflecting the changes to the offer contents. 7. Saves the latest results as the current state of the offer. 8. Disconnects from the source repository. By default, the CDS Server creates a package consisting of the new or updated documents returned by the offer query and copies the documents into a cache directory on the CDS Server. When a subscription is run for that offer, the CDS Server sends the documents from its cache. For Documentum repository or file-system repositories, you can create offers for which the offer query retrieves references to documents in the source repository instead of the documents themselves. When the CDS Server runs the offer query, it creates a package consisting of document identifiers rather than documents. When a subscription is run for that offer, the CDS Server retrieves the identified documents from the repository and sends them to the subscriber. This option, called retrieve content by reference, reduces the amount of space required in the CDS Server cache directory but increases the time required to fill a subscription. When the time comes to run a subscription, the server performs these steps: 1. Identifies the subscriber and the offers from the subscription. 2. Verifies that the subscriber still has access to the offers and that the offers have not expired. For any expired offers, the CDS Server notifies the subscriber that the offer s content will not be included. 3. For ICE subscriptions, checks whether the subscriber confirmed delivery of all previous packages. If any confirmations are outstanding, the CDS Server waits for the amount of time specified in its configuration file, then checks again. If the Documentum Content Distribution ServicesTM Administration Guide 17

18 Introducing Documentum Content Distribution Services confirmation has not been received, the CDS Server stops the subscription and notifies the subscriber. 4. Checks the subscription to determine which package the subscriber last received for each subscribed offer. 5. For each offer in the subscription, compares the historical package number to the current package number for the offer. If there are no new packages, no further action is necessary and the server skips the remaining steps. 6. Creates a delivery package consisting of the changes to the offers since the last packages received by the subscriber. For offers that retrieve content by reference, the CDS Server connects to the source repository and retrieves the documents; for other offers, the documents are retrieved from the CDS Server cache. 7. Prepares the delivery package by applying any associated templates. 8. Attempts to deliver the package to the subscriber using the protocol and address from the subscription. 9. If delivery fails, the server logs the error. The subscriber will not receive any updates until the next time the subscription runs. 10. When delivery succeeds, the server updates the subscription to record delivery of the package. What the CDS Server retrieves from the repository? The selection query for an offer returns a list of the documents that make up the offer. By default, the CDS Server retrieves the documents from the repository and copies them into a cache directory. For each document, the CDS Server attempts to retrieve: A content file A set of attributes describing the content file, such as its name and revision date The content file is the primary file that the CDS Server delivers to subscribers. The attributes provide metadata that the CDS Server uses to control the distribution process. For example, it uses the revision date attribute to determine whether a given document has changed since the last time the offer was run. The CDS Server creates an XML file for each content file containing its attribute information. The XML file may or may not be sent to subscribers as part of the offer, depending on whether the subscription requests the metadata. Note: The What the CDS Server delivers to subscribers?, page 20 contains information on Documentum repositories, Site Caching Services repositories, and relational databases, the selection query may also return additional user-defined attributes, which are added to the XML file. 18 Documentum Content Distribution ServicesTM Administration Guide

19 Introducing Documentum Content Distribution Services For file-based repositories, the content file is the file as it exists in the file system. The file system also supplies the attribute values for the file, such as its filename and last modified date. For Documentum repository offers, the content file is one rendition of a specific version of the Documentum repository object. By default, the CDS Server retrieves the primary rendition of the current version, but the offer can specify a different rendition or version. The attributes retrieved from the repository are the ones for the selected rendition and version. The CDS Server determines whether the file has changed since the last time the offer was run by comparing the value of the r_modify_date attribute to its previous value. For Site Caching Services repositories, the content file is the file as it exists in the Site Caching Services target root directory. The CDS Server uses the last modified date on the file to determine whether a given document has changed. File attributes are retrieved from the Site Caching Services property tables. The selection query for a database offer is a SQL statement. The CDS Server identifies the content file and attributes by looking for specially named columns in the result set: The value in the CONTENT column is the content file. The value in the FILENAME column is the name to use for the content file. The value in the VERSION column is used to determine whether the content file has changed since the last time the offer was run. The value in the ID column is used as the unique identifier for the document. Note: The result set needs to use these column names. If the column names in the relational database are different, use the SQL AS command to use these names as aliases. If the SQL result set does not include one or more of these columns, or if the value for that column is missing, the CDS Server uses these defaults: If a CONTENT value is missing, the content file is empty. If a FILENAME value is missing, the filename is null. If a VERSION value is missing, the CDS Server sets the attribute value to INITIAL. The CDS Server will not recognize new versions unless the VERSION is updated. If a ID value is missing, the CDS Server assigns a system-generated identifier. The identifier may be different each time the offer is run, causing the CDS Server to resend the same document multiple times. If the SQL selection query returns any additional columns, the column/value pairs are stored as user-defined attributes. Documentum Content Distribution ServicesTM Administration Guide 19

20 Introducing Documentum Content Distribution Services What the CDS Server delivers to subscribers? When a subscriber receives a package from the CDS Server, it contains the content files retrieved from the source repository. If the subscription includes one or more templates, the CDS Server applies them before delivering the package. The filenames of the delivered files are determined by the file s FILENAME attribute, whose value the CDS Server sets on the basis of the offer selection query (The What the CDS Server retrieves from the repository?, page 18 contains more information). For files from a repository, Content Server adds the standard DOS extension if the file s object name does not already include it. If the subscription includes applying one or more templates to the content files, the template may change the filename; the Creating templates, page 52 contains more information on this. If the subscription has the Send metadata option selected, the package sent to the subscriber also includes the XML files containing attribute information for each content file. The Creating offers, page 36 contains more information on how to select which attributes to deliver, and the Appendix B, Attribute File XML Format contains more information on the structure of the file. The XML file names match the corresponding content files except for their extension. The attribute files appear in a.cxf subdirectory of the directory containing the content files. Once a subscriber has received the initial package for an offer, subsequent packages may contain instructions to delete items the subscriber has already received. Only ICE subscribers receive deletion instructions; FTP and subscribers do not. Using CDS Content Distribution Services recognizes two types of users: Administrators, who represent the content distributor or provider Subscribers, who receive content from the distributor Every distributor has at least one administrator. Administrators are responsible for defining what content is available and which subscribers have access to it. Using Content Distribution Services Administrator (CDS Administrator), they create offers, templates, and subscriber accounts. Administrators also maintain and troubleshoot the CDS Server. The Administrator tasks, page 21 contains more information. Subscribers are responsible for maintaining their local repositories, which includes making sure that the repository is correctly updated with the content they receive from the distributor. Depending on the policies of the distributor, subscribers may log in to CDS Administrator to create their own subscriptions, or the distributor may have an administrator create subscriptions on their behalf. The Subscriber tasks, page 21 contains more information. 20 Documentum Content Distribution ServicesTM Administration Guide

21 Introducing Documentum Content Distribution Services Administrator tasks The tasks required to administer Content Distribution Services fall into two major categories: those you perform at installation time to set up the initial distribution framework, and those you perform on an on-going basis to maintain the system. You need to perform the initial setup tasks for Content Distribution Services in order. 1. Install and configure the software by following the instructions in Installing Documentum Content Distribution Services. 2. Define the content that is available for distribution by creating offers and templates in CDS Administrator. The Chapter 3, Offering Content contains more information. 3. Register subscribers using CDS Administrator. In many cases, you also need to deliver the CDS Client software to the subscriber. The Chapter 4, Registering subscribers contains more information. 4. Create subscriptions or provide your subscribers with instructions for creating their own. The Chapter 5, Subscribing to Offers contains more information. You may perform ongoing maintenance tasks as needed. Register new subscribers by creating their user accounts. The Chapter 4, Registering subscribers contains more information. Create subscriptions for new and existing subscribers, unless you allow subscribers to create their own subscriptions. The Chapter 5, Subscribing to Offers contains more information. Create new offers and inform subscribers about their availability. TheChapter 3, Offering Content contains more information. Monitor the CDS Server processing. The Chapter 7, Monitoring Server Processing contains more information. Subscriber tasks The tasks required for a subscriber depend on the policies of the content distributor and on the protocol in which the subscriber receives content. The major steps involved in subscribing to an offer are described below. 1. Contact the distributor to learn what content is available to you and identify which offer you want to subscribe to. 2. Determine whether you need to install and configure the Documentum CDS Client. The CDS Client enables you to receive content using the ICE protocol and update Documentum Content Distribution ServicesTM Administration Guide 21

22 Introducing Documentum Content Distribution Services your target repository automatically. If you will use the CDS Client, install it according to instructions provided by the content distributor or from Installing Documentum Content Distribution Services. 3. Collect the information the distributor needs in order to deliver the content. The necessary information depends on the delivery protocol. ICE subscribers need the URL for the CDS Client. For details about the CDS Client, the Chapter 6, Using the Content Distribution Services Client Application contains more information. FTP subscribers need the URL for the FTP server and directory as well as the login information for a user account the CDS Server can use to log in to the FTP server. subscribers need the address to which the CDS Server sends the offer content. 4. Create a subscription to the offer. Depending on the policies of the distributor, you may create your own subscriptions or provide the relevant information to the distributor. The Chapter 5, Subscribing to Offers contains more information on creating your own subscriptions. 5. If you are an ICE subscriber, configure the subscription using CDS Client. The subscription is not complete until you perform this step. The Chapter 6, Using the Content Distribution Services Client Application contains more information. 6. If necessary, develop a process for post-processing the delivered content. If you receive the content in zipped format, you may need to unzip it to make it available in the target repository. 22 Documentum Content Distribution ServicesTM Administration Guide

23 Chapter 2 Using CDS Administrator Content Distribution Services Administrator (CDS Administrator) is a Web-based application that runs on the CDS Server. You use it to define the objects that make up your distribution scheme. This chapter describes the basic mechanics of using CDS Administrator: Logging in, page 23 Navigating in the application, page 24 Scheduling offers and subscriptions, page 29 Sending notifications, page 33 Logging in To log into CDS Administrator: 1. Point your browser to the URL <web_server> is the name of the Web server hosting the application and <port_number> is the port that CDS Administrator monitors. 2. Enter your Content Distribution Services login name and password. When you enter the password, asterisks display in place of the characters you type for security purposes. 3. Click Login. The main screen appears. The menu along the left displays the object types you have security access to: all types if you are designated as an administrator, or just your subscriptions and user information if you are not. If the login is unsuccessful, a message appears beneath the Login name and Password fields indicating the problem. Correct the problem and try again. If the problem persists, consult your system administrator. Documentum Content Distribution ServicesTM Administration Guide 23

24 Using CDS Administrator Navigating in the application The main menu for CDS Administrator always appears on the left. If you are logged in as an administrator, the menu lists the major object types that you create: Subscribers Groups Offers Templates Subscriptions If you are logged in as a subscriber who is not part of the administration group, you can only create and modify your own subscriptions and user information; you can access only Subscriber Info, Subscriptions and a read-only list of the Offers available to you. Across the top of the screen is a header that identifies the application, shows your user name, and gives access to the online help. Across the bottom of the screen is a message area where CDS Administrator displays status messages. Error messages, should they occur, appear in the area just below the page name. The pages in CDS Administrator are organized into sets based on which object type they relate to. The structure of each set of pages is similar: When you select an object type from the menu, the list page for that object type appears. You use this page to select the object you want to work with or to create a new one. For details about using the list page, the Using list pages, page 25 contains more information. When you select or create an item from the list page, the application displays the first property page for that object. You use this page to enter details about the object. The property pages differ for each object type. Most Content Distribution Services objects have a series of property pages. The names of the pages appear, in the order that you should complete them, in the tab list between the menu and the current property page. Tabs for pages that are optional appear in italics. Click the page name in the tab list to move to that page. At the bottom of property pages is a button bar with buttons for moving back and forth between the property pages and for saving your changes. The Finish button saves the object and returns you to the list page. If the Finish button does not appear, it means you have not yet entered all required information. Note: It is important that you click the Finish button. If you proceed without clicking the Finish button, your changes will not be saved. Use the Display Help checkbox in the upper right to decide whether to display onscreen help text that gives tips for using the controls. When the box is selected, the help text appears on the right; when the box is not selected, the help text does not appear, freeing up some screen space. 24 Documentum Content Distribution ServicesTM Administration Guide

25 Using CDS Administrator Figure 2-1. Parts of the CDS Administrator screen CDS Administrator considers all property pages associated with a particular object as a single unit of work. When you click the Finish button, the application saves the changes from all the property pages for this object, not just the current one. Similarly, the Cancel button cancels all changes. Note: It is important to click the Finish button to save the changes you have made. Without clicking the Finish button, if you move to a different page, your changes will not be saved. Using list pages When you select an object type from the main menu, the first page that appears is the list page for that object type. The list page provides a variety of options for displaying the available objects as well as buttons for creating and deleting objects. Documentum Content Distribution ServicesTM Administration Guide 25

26 Using CDS Administrator Figure 2-2. List Page By default, the list page displays up to the first 10 items, sorted alphabetically by name. You can change the number of items displayed on the page at one time by selecting a number from the Show Items dropdown list. You can change the sort order by clicking the column name for the column you want to sort by; click once to sort in ascending order, then again to sort in descending order. The text next to the Show Items box shows how many items can be displayed on the page. If there are more items than can show on one page, click to view the next set of items or to view the previous set. The and buttons take you to the beginning and end of the list respectively. To move to a specific set of items, enter a page number in the Page box. To jump directly to an item whose name you know, enter the initial letters of the name into the box on the right, then click Go. To add a new item, click the Create Object button, where Object is the object type listed on this screen. A blank property page for this object type appears. To modify an existing item, click the name of the item you want or the Info icon next to it. The first property page for the selected object appears. To delete one or more items, select the checkbox next to the items, then click the Delete Object button. CDS Administrator asks you to confirm that you want to remove the items from the system. The message also reminds you that deleting these objects may result in deleting other dependent objects; for example, deleting an offer deletes all associated subscriptions. Click Delete to continue or Cancel to stop the deletion. 26 Documentum Content Distribution ServicesTM Administration Guide

27 Using CDS Administrator Other buttons may appear as well, depending on which object type is listed. For Subscribers, Groups, and Offers, the Notify Object button takes you to the Send Notification page so that you can send a message. Select the checkbox next to the names of the subscribers or groups you want to send the message to, or the offers whose subscribers you want, then click the Notify Object button. For information about sending notifications, the Sending notifications, page 33 contains more information. For Offers and Subscriptions, the Run Object button executes the selected offer or subscription immediately, regardless of its schedule. CDS Administrator displays a page asking you to confirm that you want to run the offer or subscription. Click Start to run it or Cancel to return to the list page without running it. For Offers, the Create Subscription button provides a shortcut to the property pages for subscribing to the offers selected in the list. The Preview Subscription button displays a list of the documents that would be included in a subscription to the selected offers. Using attributes pages Each of the objects you create in CDS Administrator has a property page called Attributes, which you use to specify a category for the object. You also have the option to assign additional user-defined attribute values to the object. Figure 2-3. Attributes page Documentum Content Distribution ServicesTM Administration Guide 27

28 Using CDS Administrator An object s category appears on the list page and on selection pages. Clicking on the Category column sorts the objects on the list page into groups based on their category; selecting a category on a selection page displays only objects of that category. If you add other attributes to the object, their values are stored with the object definition in the CDS database, but they do not appear on the list page or any other place in the user interface. When you create a new object, the category is set to a default value specified in the CDS Server configuration file cds.xml unless you enter a different value in the Category box. As delivered, the default category is DEFAULT. To add an attribute, enter the name of the attribute in the Attribute box and its value in the Value box, then click Add. To remove an attribute, highlight it in the Attributes box and click Remove. Using selection pages Most of the objects you create in CDS Administrator have at least one property page that requires you to select one or more related objects of another type. For example, when you create a subscriber, you select which offers the subscriber can subscribe to, and when you create an offer, you select which templates are available for the offer. The figure below shows the page you use to select the offers that a subscriber can subscribe to, but the available options are the same regardless of what type of object you are selecting. Figure 2-4. Selection page 28 Documentum Content Distribution ServicesTM Administration Guide

29 Using CDS Administrator The Available listbox on the left shows the objects that are available; the Selected listbox on the right shows the objects already selected. The Category box above the Available list enables you to control which objects appear in the Available list. To select an object, you move it from the Available box to the Selected box. You can do that in these ways: Double-click the object name in the Available list. Highlight the name in the Available list, then click Add >. Click Add All >> to select all available objects. To deselect an object, you move it from the Selected box to the Available box. You can do that in these ways: Double-click the object name in the Selected list. Highlight the name in the Selected list, then click < Remove. Click << Remove All to deselect all selected objects. Scheduling offers and subscriptions When you create offers and subscriptions, you specify a schedule on which the CDS Server runs them. The schedules are independent of each other. For example, suppose you schedule an offer to run every four hours, and a subscription to that offer runs twice a day (every twelve hours). The server may create as many as three new packages between sending updates to the subscriber. When the subscription runs, the server delivers to the subscriber all packages created since the last time the subscription ran. Note: When creating schedules, it is mandatory to fill in the details on Info and Query screens, while editing/creating offer before you create schedules. When editing subscription, it is mandatory to fill in the details on Info and Destination screens before you create schedules for subscriptions. Documentum Content Distribution ServicesTM Administration Guide 29

30 Using CDS Administrator Figure 2-5. Schedule page Clicking on Schedule, lists all the schedules you have created. Click on the type of schedule to view the Schedule property page. The Schedule property pages for offers and subscriptions present the same scheduling options, which are described in the procedure below. 30 Documentum Content Distribution ServicesTM Administration Guide

31 Using CDS Administrator Figure 2-6. Schedule property page This procedure assumes you are on the Schedule property page for an offer or a subscription. For information about getting to this page as part of defining the object, the Chapter 3, Offering Content or Chapter 5, Subscribing to Offers contains more information. To schedule an offer or subscription: 1. Select the base schedule frequency. The value you choose from the Run box determines what controls appear on this page and how many steps of this procedure you need to complete. The options are: One Time Weekly Monthly The server runs the offer or subscription once, at a specified date and time. The One Time option is appropriate for static offers whose contents do not change over time. The server runs the offer or subscription on specified days of the week, one or more times each day. The server runs the offer or subscription on specified dates each month, one or more times each day. 2. Enter a start date when the server first runs the offer or subscription. Documentum Content Distribution ServicesTM Administration Guide 31

32 Using CDS Administrator To start the schedule immediately, select Now. The Now option is the default for Weekly and Monthly schedules, and is not available for One Time schedules. To start the schedule later, select Specify and enter a future date and time. Click the calendar icon to select the date, or type it using the format MM/DD/YY. The format for the time is HH:MM, followed by AM or PM. If you omit the time, the schedule starts at midnight. If you selected One Time, the schedule is complete. You do not need to complete the rest of this procedure. The server will run the offer or subscription at the specified time. 3. Enter the stop date when the server stops running the offer or subscription. To keep the schedule active until someone changes it, select Never. To stop the schedule after a limited time, select Specify and enter a date and time. The date and time must be later than the start date and time. 4. Identify the days on which to run the offer or subscription. For a Weekly schedule, select each day of the week when the CDS Server should run the offer or subscription. For a Monthly schedule, enter the day number for each date when the CDS Server should run the offer or subscription. Separate the numbers with commas. For example, to run an offer on the 15th and 30th of each month, enter 15, Identify how often to run the offer or subscription on each scheduled day. To run once a day, select Once and enter the time. The format for the time is HH:MM, followed by AM or PM. If you omit the time, the schedule starts at midnight. To run multiple times per day, select Repeat every and indicate how often to repeat. Enter a number in the text box and select minutes or hours. Also select a starting and ending time for each day; the default is 9 AM to 5 PM. If you select minutes, the offer or subscription runs every specified number of minutes, starting at the top of the hour and repeating each time that number of minutes passes within a single hour. For example, if you repeat every 15 minutes, the offer or subscription runs each hour at 15, 30, and 45 minutes past the hour (but not at the top of the next hour). If you select hours, the offer or subscription runs every specified number of hours at the top of the hour. 6. Click Finish to save the changes. Note: After clicking the Finish button on Schedule properties page, it is important that you click the Finish button on the offer/subscription screen. If you proceed without clicking the Finish button on the offer/subscription screen, your changes will not be saved. 32 Documentum Content Distribution ServicesTM Administration Guide

33 Using CDS Administrator Deleting schedules The Delete Schedules button is available on the schedule list page. To delete schedules: 1. Select the checkbox against the schedule. 2. Click Delete to delete the schedule. 3. The system prompts you to confirm the schedules to be deleted. 4. Click OK to confirm. 5. Click Finish button on the offer/subscription page to delete the schedule. Note: After clicking the Finish button on Schedule properties page, it is important that you click the Finish button on the offer/subscription screen. If you proceed without clicking the Finish button on the offer/subscription screen, your changes will not be saved. Sending noti cations CDS Administrator provides a facility for sending messages to subscribers, enabling administrators to keep them informed about new offers or administrative bulletins. When you send notifications from the Offers list page, the CDS Server delivers the notifications differently for subscribers who receive offer content using the ICE protocol: the server sends these notifications to the subscriber s CDS Client application as well as to their address. FTP and subscribers receive the notifications through only. Administrators use this page to send personally composed messages to subscribers. In addition to these messages, subscribers receive automatic notification from the CDS Server when updates are made that affect their subscriptions. For example, the CDS Server notifies subscribers when an offer they subscribe to is deleted or removed from the list of offers they can access. Administrators can reach the notification page from the list pages for Subscribers, Groups, and Offers. To send a noti cation: 1. Select the users you want to send the message to. On the Subscribers list page, click the checkbox next to the individual subscribers who should receive the message. Documentum Content Distribution ServicesTM Administration Guide 33

34 Using CDS Administrator On the Groups list page, click the checkbox next to the groups whose subscribers should receive the message. On the Offers list page, click the checkbox next to the offers whose subscribers should receive the message. 2. Click the Notify Object button. The Send Notification page appears. The text in the upper left indicates who this message will be sent to. 3. Enter a subject line for the message. The subject line is the text that appears in the recipient s inbox. 4. Select a message priority for ICE notifications. The Priority setting has no effect for notifications. 5. Enter the body of the message in the Message box. 6. Click Notify to send notification to the subscribers. 34 Documentum Content Distribution ServicesTM Administration Guide

35 Chapter 3 Offering Content The core of Documentum Content Distribution Services is the offer. An offer is a collection of documents or other content that you are making available to subscribers. In other words, the offer is the content you are distributing. In addition to distributing the content, Content Distribution Services enables you to modify the raw content before distributing it to subscriber. The CDS Server can apply templates to the content of an offer. This chapter explains how to create the two content-related object types from the main menu of CDS Administrator: Before you begin, page 35 Creating offers, page 36 Creating templates, page 52 Before you begin Before you can create an offer, you must perform these preparatory tasks: Make sure the CDS Server can locate the source repository and connect to it. For repositories, you specify the connection information when you create the offer. You also need to provide the login information for the user account the CDS Server uses to log in to the repository. The user must have at least Read access to the items it retrieves from the repository. For relational databases and Site Caching Services repositories, you must configure a data source on the application server. The Installing Documentum Content Distribution Services contains more information. The Site Caching Services target root directory must be accessible from the CDS Server host machine. Identify the selection criteria to use to select which documents the offer includes. Documentum Content Distribution ServicesTM Administration Guide 35

36 Offering Content For Documentum repositories, the selection criteria include which folders contain the documents and what attribute values to verify against. For Site Caching Services repositories, the selection criteria are what attribute values to verify against. For file-system repositories, the selection criteria are which folders contain the documents and what pattern the filenames must match. For databases, the selection criteria are captured in a SQL statement that selects the appropriate data. For Documentum repositories, determine which versions, renditions, and attributes to include in the offer. Decide whether to put an upper limit on the number of documents in the offer. Decide how often to run the offer, based on how often updates are expected. Decide whether to enter a value in Max delete limit text box in the offer. For Documentum repositories or file-system repositories, decide whether the documents in an offer should be retrieved from the repository when the offer is run or when the subscription is run. The What the CDS Server does?, page 17 contains more information on retrieving content by reference option. Create any templates that apply to the offer contents. The Creating templates, page 52 contains more information. Creating offers Once you have completed the preparatory tasks, you are ready to create the offer. To create an offer, you specify: Where the content comes from (the source repository)? What content comprises the offer (the offer query)? When and how often the CDS Server runs the offer (the offer schedule)? What templates to make available for transforming the content of the offer? The procedure below explains how to create a new offer or modify an existing offer. The steps are the same in either case. When creating a new offer, you must follow the steps in the order they appear. When modifying an offer, you can generally skip directly to the step that relates to the item you want to change. You must be logged in as an administrator to create or modify offers. If you are logged in as a subscriber, you can view the list of offers available to you but cannot modify them. To create or modify an offer: 1. Select Offers from the menu. 36 Documentum Content Distribution ServicesTM Administration Guide

37 Offering Content The Offers page appears, with a list of the existing offers. For more information about using this page to review the existing offers, the Using list pages, page 25 contains more information. 2. Click the Create Offer button to define a new offer, or click the icon next to the offer you want to modify. The Offer Info page appears. It is the first of a series of pages you use to define the offer. 3. Enter a name and description for the offer. 4. Specify when the offer is available. By default, the offer is available to subscribers as soon as you create it (New) and never expires. However, you can specify a start and end date for the offer. Note: The offer start and end date specify when the offer is available to subscribers. These dates are independent of the offer creation schedule. To specify a different start date for the offer, select Embargo until, then choose a date and time. Click the calendar icon to select the date, or type it using the format MM/DD/YY. The format for the time is HH:MM, followed by AM or PM. To specify a different end date for the offer, select Expires at, then choose a date and time. 5. Move to the Attributes page. 6. Enter a category and attributes for the offer. Documentum Content Distribution ServicesTM Administration Guide 37

38 Offering Content Category is set to the default value specified in the CDS Server configuration unless you enter a different value; additional attributes are optional. For more information about categories and attributes, the Using attributes pages, page 27 contains more information. 7. Move to the Query page. The controls that appear on this page differ depending on whether the source repository is a Documentum repositories, a Site Caching Services repository, a relational database, or a file-based repository. 8. Select what type of repository the offer content comes from. The subscription server needs to know what type of repository the content is coming from so that it can use the appropriate method to retrieve it. The valid Source type values are: Documentum Content Server The content is stored in a Documentum repository Documentum Content Server (DQL) The content is stored in a Documentum repository, and you will write a DQL WHERE clause to select the appropriate documents File system The content is stored in a folder of the file system Database The content is stored in a relational database Site Catching Services The content is stored in a Documentum Site Caching Services repository 9. Enter the selection criteria for the content. The page has different options depending on the Source type you selected in step 8. The Specifying the offer query, page 39 contains more details. 10. Move to the Templates page. 11. Select the templates that are available for this offer, if any. For information about using templates to transform offer content, the Preparing content for delivery: Templates, page 13 contains more information. The Using selection pages, page 28 contains more information on using this page to select templates. 12. Move to the Groups page. 13. Select the groups that have the right to subscribe to this offer. Any users who are part of the selected groups can subscribe to the offer. Selecting a group on this page makes the offer available to the users in that group. It does not create a subscription. For more information about using this page to select groups, the Using selection pages, page 28 contains more information. 14. Move to the Users page. 38 Documentum Content Distribution ServicesTM Administration Guide

39 Offering Content 15. Select the users that have the right to subscribe to this offer. You only need to select users who are not members of the groups you selected on the previous page. Users can subscribe both to offers assigned to them as individuals and those assigned to groups they belong to. Selecting a user on this page makes the offer available to the user. It does not create a subscription. For more information about using this page to select users, the Using selection pages, page 28 contains more information. 16. Move to the Schedule page. 17. Define the offer schedule. The offer schedule determines when (and how often) the CDS Server runs the query you built. The Scheduling offers and subscriptions, page 29 contains more details. 18. Move to the Preview page. The Preview page displays information about the documents that are included in this offer. The format is similar to a list page. The Preview option is not available for offers that have expired. 19. Click the Finish button to save the offer. The Offers list page appears with the new offer in the list. Note: When you create a new offer, remember that you need to give the appropriate subscribers access to the offer before they can subscribe to it. The Chapter 4, Registering subscribers contains more details. Specifying the offer query This section explains how to create the query that defines the content of the offer. You create the query on the Query page, which is one of the property pages for offers. The page and the process differ depending on what type of source repository you are retrieving content from: Documentum Content Server Documentum Content Server (DQL) File system Relational database Site Caching Services Note: The Documentum Content Server options are not available if the CDS Server does not have Documentum Foundation Classes (DFC) installed. The Installing Documentum Content Distribution Services contains more details. Documentum Content Distribution ServicesTM Administration Guide 39

40 Offering Content The procedures below assume that you are on the Query page for the offer. For information about getting to the Query page, the Creating offers, page 36 contains more information. You use the same procedures to modify existing queries, however you can generally skip directly to the step that relates to the item you want to change. To create an offer query for a Documentum repository: 1. Select Documentum Content Server from the Source type dropdown list. The page displays the controls for defining a repository query. 2. Select the repository to retrieve the content from. 40 Documentum Content Distribution ServicesTM Administration Guide

41 Offering Content The Selected repository dropdown list shows the repository that the CDS Server has access to. If the repository you want does not appear in the list, you need to update the CDS Server configuration. The Installing Documentum Content Distribution Servicescontains more information. 3. Enter the user name and password for the CDS Server to use to log into the repository. The user must have at least Read access to the items it retrieves from the repository. When you enter the password, asterisks appear in place of the characters you type for security purposes. 4. Identify what type of repository object to retrieve. You identify the object type by entering the internal name of the object type. The default is dm_document, which stores document objects. You can only identify one type, and it must be dm_document or one of its subtypes. 5. Enter the complete path to the repository folder that contains the content. The path must start from the root of the repository. If the content resides in more than one folder, select the common parent. The offer includes items from this folder as well as its subfolders. 6. Identify which version of each item to retrieve from the repository. Enter the version label in the Version box. The default value is CURRENT, which selects the more current version of the item. The Content Server documentation contains more information on versions and version labels. You can only enter one version label. 7. Identify which renditions of the item to retrieve from the repository. Leave the Rendition box empty to retrieve the primary rendition for each item. To retrieve a specific rendition, enter the format name for the rendition in the Rendition text box and click Add. The Content Server documentation contains more information about versions and version labels. 8. If you enter one or more rendition formats, determine what the CDS Server does when an item does not have a rendition in any of the specified formats. Select Required if you want to be sure that all items in the offer are in one of the specified formats. If the CDS Server does not find any of the specified renditions for an item, it does not include a content file for the item in the offer. If the offer uses the Send metadata option, the item s attributes are still included in the offer. Select Preferred if you want the CDS Server to retrieve the primary rendition for an item if the specified renditions are not available. 9. Indicate the maximum number of items to include in the offer. By default the offer includes all items that match the criteria. To limit the number of items in the offer, select the Limit to option and type the maximum number in Documentum Content Distribution ServicesTM Administration Guide 41

42 Offering Content the text box. If more items match the criteria, the CDS Server excludes those that exceed the maximum. 10. Specify whether to retrieve documents from the repository when the offer is run or when a subscription runs. If the Retrieve content by reference checkbox is not selected (the default), the CDS Server copies the selected documents into a cache directory when it runs the offer query. If it is selected, the CDS Server retrieves document identifiers when it runs the offer query, but does not retrieve the documents until it runs a subscription for this offer. The Before you begin, page 35 contains more information on this option. Note: You cannot change the value of the Retrieve content by reference option once you have saved the offer. When modifying an existing offer, this checkbox appears as read-only. 11. To set options related to object attributes, click Show Options for Attributes. You can use object attributes for two purposes: To deliver attribute values for each item as part of the offer To filter which items the CDS Server includes in the offer based on attribute values If neither of these options is relevant for the offer, you can skip the remaining steps in this procedure. The offer query is complete. When you click Show Options for Attributes, the page expands to display attribute options. 12. Choose which attribute values to deliver as part of the offer. 42 Documentum Content Distribution ServicesTM Administration Guide

43 Offering Content When the offer includes attributes, the CDS Server delivers an XML file along with each item containing the attribute values for that item. The section What the CDS Server delivers to subscribers?, page 20 contains more information. To include an attribute, enter its name in the Attribute box and click Add. To remove an attribute, highlight it in the Attributes to send box and click Remove. 13. Identify filtering conditions for the offer query based on attribute values. When you include attribute filters, the offer includes only those items whose attribute values match the filter values. If the attribute can have repeating values, the offer includes items where any of the values match the filter value. If you enter multiple attributes, the offer includes items whose values match all of the filter values. Enter the name of the attribute in the Attribute box and the value the item must match in the Value box, then click Add. The attribute name/value pair appears in the Attributes to filter box. The value appears inside of square brackets so that you can view any leading or trailing spaces. 14. Specify the maximum number of items that are allowed to be deleted during the offer run in the Max delete limit text box. To enable this option, specify any value greater than zero (the default value is zero). When the number of documents to be deleted exceeds the specified limit, the CDS Server stops offer execution. Consequently, the CDS Server will not create a package and a notification mail is sent to CDS Administrator. This offer will be blocked for further execution from scheduled run. This can be tracked in cds_trace file. To run the blocked offer, select the offer from Offer list page and click Run Offer. Note: This feature disables bulk deletion of documents without the consent of CDS Administrator. 15. Continue with defining the offer. Documentum Content Distribution ServicesTM Administration Guide 43

44 Offering Content To create an offer query for a repository using a DQL WHERE clause: 1. Select Documentum Content Server (DQL) from the Source type dropdown list. The page displays the controls for defining a repository query. 2. Select the repository to retrieve the content from. The Selected repository dropdown list shows the repositories that the CDS Server has access to. If the repository you want does not appear in the list, you need to 44 Documentum Content Distribution ServicesTM Administration Guide

45 Offering Content update the CDS Server configuration. The Installing Documentum Content Distribution Services contains more information. 3. Enter the user name and password for the CDS Server to use to log into the repository. The user must have at least Read access to the items it retrieves from the repository. When you enter the password, asterisks appear in place of the characters you type for security purposes. 4. Identify what type of repository object to retrieve. You identify the object type by entering the internal name of the object type. The default is dm_document, which stores document objects. You can only identify one type, and it must be dm_document or one of its subtypes. 5. Enter the complete path to the parent repository folder that contains the content. The initial forward slash (/) represents the root of the repository. If the content resides in more than one folder, select the common parent. The offer includes items from this folder as well as its subfolders. If the DQL WHERE clause (entered at step 8) selects any documents outside of this parent folder and its descendents, they are not included in the offer. 6. Identify which renditions of the item to retrieve from the repository. Leave the Rendition box empty to retrieve the primary rendition for each item. To retrieve a specific rendition, enter the format name for the rendition in the Rendition text box and click Add. The Content Server documentation contains more information. 7. If you enter one or more rendition formats, determine what the CDS Server does when an item does not have a rendition in any of the specified format. Select Required if you want to be sure that all items in the offer are in one of the specified formats. If the CDS Server does not find one of the specified renditions for an item, it leaves the item out of the offer. Select Preferred if you want the CDS Server to retrieve the primary rendition for an item if the specified renditions are not available. 8. Enter a DQL WHERE clause that selects the documents to include in the offer. Do not include the keyword WHERE, only the selection criteria. The WHERE clause needs to select the desired version of the documents. 9. Indicate the maximum number of items to include in the offer. By default the offer includes all items that match the criteria. To limit the number of items in the offer, select the Limit to option and type the maximum number in the text box. If more items match the criteria, the CDS Server excludes those that exceed the maximum. 10. Specify whether to retrieve documents from the repository when the offer is run or when a subscription runs. Documentum Content Distribution ServicesTM Administration Guide 45

46 Offering Content If the Retrieve content by reference checkbox is not selected (the default), the CDS Server copies the selected documents into a cache directory when it runs the offer query. If it is selected, the CDS Server retrieves document identifiers when it runs the offer query, but does not retrieve the documents until it runs a subscription for this offer. The Before you begin, page 35 contains more information. Note: You cannot change the value of the Retrieve content by reference option once you have saved the offer. When modifying an existing offer, this checkbox appears as read-only. 11. To specify which object attributes to include as part of the offer, click Show Options for Attributes. When you click Show Options for Attributes, the page expands to display the attribute option. 12. Choose which attribute values to deliver as part of the offer. When the offer includes attributes, the CDS Server delivers an XML file along with each item containing the attribute values for that item. The What the CDS Server delivers to subscribers?, page 20 contains more information. To include an attribute, enter its name in the Attribute box and click Add. To remove an attribute, highlight it in the Attributes to send box and click Remove. 13. Indicate the maximum number of items that are allowed to be deleted during the offer run in the Max delete limit text box. To enable this option, specify any value greater than zero (the default value is zero). When the number of documents to be deleted exceeds the specified limit, the CDS Server stops offer execution. Consequently, the CDS Server will not create a package and a notification mail is sent to the CDS Administrator user. This offer will be blocked for further execution from scheduled run. This can be tracked in cds_trace file. To run the blocked offer, select the offer from Offer list page and click Run Offer. Note: This feature disables bulk deletion of documents without the consent of CDS Administrator user. 14. Continue with defining the offer. 46 Documentum Content Distribution ServicesTM Administration Guide

47 Offering Content To create an offer query for a le-based repository: 1. Select File system from the Source type dropdown list. The Query page displays the controls relevant to file-based repositories. 2. Enter the path to the directory containing the content. You must enter the full directory path in the File path box, starting with the drive letter. 3. Specify a pattern that the file name must meet. To include more than one pattern, separate the patterns with commas. If you leave the File mask box blank, the offer includes all files in the selected directories, equivalent to the pattern *.*. 4. Indicate whether to include content from subdirectories. By default, the CDS Server recursively searches all subdirectories of the directory from step 2, and includes all matching files in the offer. If you do not want the server to search all subdirectories, select Down to level and enter the number of subdirectory levels to include. To search only the top-level directory (no subdirectories), enter Indicate the maximum number of files the query should return. By default the offer includes all files that match the criteria. To limit the number of files in the offer, select the Limit to option and type the maximum number in Documentum Content Distribution ServicesTM Administration Guide 47

48 Offering Content the text box. If more files match the criteria, the CDS Server excludes those that exceed the maximum. 6. Specify whether to retrieve documents from the repository when the offer is run or when a subscription runs. If the Retrieve content by reference checkbox is not selected (the default), the CDS Server copies the selected documents into a cache directory when it runs the offer query. If it is selected, the CDS Server retrieves document identifiers when it runs the offer query, but does not retrieve the documents until it runs a subscription for this offer. The Before you begin, page 35 contains more information. 7. Continue with defining the offer. To create an offer query for a database repository: 1. Select Database from the Source type dropdown list. The page displays the controls relevant to database repositories. 2. Enter the name of the data source configured for communicating with the database. The Installing Documentum Content Distribution Services document contains details on configuring a data source. 3. Enter the SQL query that selects the offer items from the database. In most cases, the query needs to return values in a column named CONTENT in order for this offer to include any items. If the query does not return a CONTENT column, the offer will need to use an associated template that retrieves attribute 48 Documentum Content Distribution ServicesTM Administration Guide

49 Offering Content information and creates content from it. The What the CDS Server retrieves from the repository?, page 18 contains more information on database selection queries. 4. Indicate the maximum number of items the query should return. By default the offer includes all items that match the criteria. To limit the number of files in the offer, select the Limit to option and type the maximum number in the text box. If more files match the criteria, the CDS Server excludes those that exceed the maximum. 5. Indicate the maximum number of items that are allowed to be deleted during the offer run in the Max delete limit text box. To enable this option, specify any value greater than zero (the default value is zero). When the number of documents to be deleted exceeds the specified limit, the CDS Server stops offer execution. Consequently, the CDS Server will not create a package and a notification mail is sent to you. This can be tracked in cds_trace file. To run the blocked offer, select the offer from Offer list page and click Run Offer. Note: This feature disables bulk deletion of documents without your consent. 6. Continue with defining the offer. To create an offer query for a Site Caching Services repository: 1. Select Site Caching Services from the Source type dropdown list. The Query page displays the controls relevant to Site Caching Services repositories. Documentum Content Distribution ServicesTM Administration Guide 49

50 Offering Content 2. Enter the name of the data source configured for communicating with the Site Caching Services database. The Installing Documentum Content Distribution Services document contains details on configuring a data source. 3. Enter the base name of the property table. The Site Caching Services database stores document information in three tables with these default names: propdb_id_s contains any single-valued attributes propdb_id_r contains any repeating-valued attributes propdb_id_m records state information about Site Caching Services publishing events In each case, id is the last eight characters of the object ID for the Site Caching Services webc target config object. The Site Caching Services documentation contains more information. The property table name you enter here is the common prefix for all three tables (propdb_id in the example). 4. If the Site Caching Services target root directory is on a different machine from the CDS Server, enter the fully qualified path to the directory. The path must identify the target root directory relative to the CDS Server, beginning with the location of the drive. On Microsoft Windows machines, the path must be a 50 Documentum Content Distribution ServicesTM Administration Guide

51 Offering Content UNC name or begin with a mapped drive letter. On Solaris machines, the path must reference the remote mount file system. If Site Caching Services is running on the CDS Server machine, leave the Root directory for cache content box blank; the CDS Server will use the Site Caching Services database to locate the cache content. 5. Indicate the maximum number of files the query should return. By default the offer includes all files that match the criteria. To limit the number of files in the offer, select the Limit to option and type the maximum number in the text box. If more files match the criteria, the CDS Server excludes those that exceed the maximum. 6. To set options related to object attributes, click Show Options for Attributes. You can use object attributes for two purposes: To deliver attribute values for each item as part of the offer To filter which items the CDS Server includes in the offer based on attribute values If neither of these options is relevant for the offer, you can skip the remaining steps in this procedure. The offer query is complete. When you click Show Options for Attributes, the page expands to display attribute options. 7. Choose which attribute values to deliver as part of the offer. When the offer includes attributes, the CDS Server delivers an XML file along with each item containing the attribute values for that item. The What the CDS Server delivers to subscribers?, page 20 contains more information. Documentum Content Distribution ServicesTM Administration Guide 51

52 Offering Content To include an attribute, enter its name in the Attribute box and click Add. To remove an attribute, highlight it in the Attributes to send box and click Remove. To include all attributes from the Site Caching Services properties database, add an asterisk (*). 8. Identify filtering conditions for the offer query based on attribute values. When you include attribute filters, the offer includes only those items whose attribute values match the filter values. If the attribute can have repeating values, the offer includes items where any of the values match the filter value. If you enter multiple attributes, the offer includes items whose values match all of the filter values. Enter the name of the attribute in the Attribute box and the value the item must match in the Value box, then click Add. The attribute name/value pair appears in the Attributes to filter box. The value appears inside of square brackets so that you can view any leading or trailing spaces. 9. Indicate the maximum number of items that are allowed to be deleted during the offer run in the Max delete limit text box. To enable this option, specify any value greater than zero (the default value is zero). When the number of documents to be deleted exceeds the specified limit, the CDS Server stops offer execution. Consequently, the CDS Server will not create a package and a notification mail is sent to the CDS Administrator user. This offer will be blocked for further execution from scheduled run. This can be tracked in cds_trace file. To run the blocked offer, select the offer from Offer list page and click Run Offer. Note: This feature disables bulk deletion of documents without the consent of CDS Administrator user. 10. Continue with defining the offer. Creating templates Templates modify or transform the content of an offer before delivering it to a subscriber. In fact, templates are sometimes called transformers. When you define an offer, you identify which templates are available for it. Subscribers can choose which of these templates, if any, to apply. Templates can be applied to the content of an individual offer or to the collective contents of multiple offers that are part of a single subscription. Templates that can only be applied to individual offers are called offer templates. Templates that can be applied to individual offers or to multiple offers in a subscription are called global templates. You identify whether a template is global when you register it with CDS Administrator. When you create a subscription, you select which (if any) of the available templates to apply to each offer in the subscription, then select which (if any) of the global templates 52 Documentum Content Distribution ServicesTM Administration Guide

53 Offering Content to apply to the subscription package as a whole. When the CDS Server runs the subscription, it applies the selected templates to each individual offer, then applies the selected global templates to the output of the offer templates. CDS Administrator does not include pages for developing JavaServer Page (JSP) templates or XSL stylesheets. Before performing the following procedure, you need to develop the XSL files and JSP templates using whatever development tool you are most comfortable with. Content Distribution Services supports several custom JSP tags related specifically to content distribution; the Appendix A, Content Distribution Services Custom JSP Tag Reference contains more information. JSP templates can include these custom tags as well as any other tags supported in the JavaServer Pages Standard Tag Library or Apache Struts framework. You do not need to do any advance development to create a ZIP template. After developing a template, you must register it in CDS Administrator before you can associate it with an offer. You must be logged in as an administrator to register templates. To register a template: 1. Select Templates from the menu. The Templates list page appears, showing a list of currently registered templates. The Using list pages, page 25 contains more information on using this page to review the existing templates. 2. Click the Create Template button to register a new template, or click the icon next to the template you want to modify. The Template Info page appears. 3. Enter a name and description for the template. The name is the text that will appear in selection lists when creating offers and subscriptions. 4. Move to the Attributes page. 5. Enter a category and attributes for the template. Category is set to the default value specified in the CDS Server configuration unless you enter a different value; additional attributes are optional. The Using attributes pages, page 27 contains more information on categories and attributes. 6. Move to the Detail page. 7. Indicate what type of template you are registering. The options are JSP, XSL, and ZIP. The bottom part of the page changes depending on which type you select. 8. To register a JSP template: a. Specify whether the CDS Server should apply this template to individual documents or collectively to the complete package. Documentum Content Distribution ServicesTM Administration Guide 53

54 Offering Content To apply the template collectively to the package, select Multiple. This option is most common for a ZIP template, where the result is a single ZIP file for the entire package rather than a separate ZIP file for each document. To apply the template to each document, make sure Multiple is not selected. b. Enter the name and location of the template file. Type the complete path and filename in the File box, or click the Browse button to navigate to and select the template file. c. Enter the extension that the CDS Server will add to the file that results from applying this template. This step is optional. If you enter an extension, do not include the period (.) at the beginning. 9. To register an XSL template: a. Enter the name and location of the template file. Type the complete path and filename in the File box, or click the Browse button to navigate to and select the template file. b. Enter the extension that the CDS Server will add to the file that results from applying this template. This step is optional. If you enter an extension, do not include the period (.) at the beginning. 10. To register a ZIP template: a. Enter the extension that the CDS Server will add to the file that results from applying this template. This step is optional. If you enter an extension, do not include the period (.) at the beginning. b. Specify whether to include a metadata file for each content file. If you select the Include Metadata checkbox, the ZIP file will include an XML file for each content file containing attributes describing the content file. If the checkbox is unselected, the ZIP file does not contain the XML files. 11. Click the Finish button to register the template or save your changes. The Templates list page appears with the new template in the list. The template is now available for associating with an offer. 54 Documentum Content Distribution ServicesTM Administration Guide

55 Chapter 4 Registering subscribers A user must be registered as a CDS subscriber in order to receive content from the CDS Server. The subscriber account definition tells the server where to send notifications and specifies which offers are available to this subscriber. Note: You also create subscriber user accounts for CDS administrators. Administrators are simply subscribers who are part of the Administrator group. This chapter tells you how to create the two user-related object types from the main menu of CDS Administrator: Creating subscriber user accounts, page 55 Creating groups, page 57 A group is a name you assign to a list of subscribers, enabling you to assign offers or send notifications to multiple subscribers at once. The Administrator group is a special group that lists the users who have administrative rights. Creating subscriber user accounts The procedure below explains how to create a new subscriber user accounts or modify an existing subscriber account. The steps are the same in either case. When creating a new subscriber account, you must follow the steps in the order they appear. When modifying a subscriber s information, you can generally skip directly to the step that relates to the item you want to change. To create subscriber accounts, you must be logged in to CDS Administrator as an administrator. If you are logged in as a non-administration subscriber, you can view and modify your own user information, but cannot change which offers you have access to; see steps 1 through 6 of the procedure. Documentum Content Distribution ServicesTM Administration Guide 55

56 Registering subscribers To create or modify a subscriber account: 1. Select Subscribers from the menu (or Subscriber Info if you are not logged in as an administrator). The Subscribers list page appears, showing a list of currently defined subscribers. The icon identifies administrators (subscribers who are part of the Administrator group); the icon identifies subscribers. The Using list pages, page 25 contains more information on using this page to review the existing subscribers. 2. Click the Create Subscriber button to define a new subscriber, or click the icon next to the subscriber you want to modify. The Subscriber Info page appears. 3. Enter a name for the subscriber. The subscriber name is the name that appears in lists when selecting a subscriber and is also the name the subscriber uses to log into CDS Administrator. 4. Enter a description of the subscriber. The description is for your information. It displays on the Subscribers list page to help you identify the subscriber. 5. Enter the subscriber s address. The CDS Server sends notifications to this address. 6. Enter the subscriber s password in the Password and Confirm password boxes. When you enter the password, asterisks appear in place of the characters you type for security purposes. Note: If you are modifying an existing subscriber, the Password and Confirm password boxes are blank. Leave them blank to retain the same password. 7. Move to the Attributes page. 8. Enter a category and attributes for the subscriber. Category is set to the default value specified in the CDS Server configuration unless you enter a different value; additional attributes are optional. The Using attributes pages, page 27 contains more information on categories and attributes. 9. Move to the Offers page. 10. Select the offers to which this subscriber can subscribe. Selecting an offer on this page makes it available to the subscriber for subscription. It does not create a subscription. Note: If you remove an offer to which the subscriber has an existing subscription, the subscriber will not receive future content updates. The subscription is not deleted, but it becomes inactive. To delete the subscription, select Subscriptions from the menu and remove it from the list page. 56 Documentum Content Distribution ServicesTM Administration Guide

57 Registering subscribers Subscribers can also subscribe to offers assigned to a group they belong to. The Creating groups, page 57 contains more details. 11. Click the Finish button to create the subscriber account or save your changes. The Subscribers list page appears with the new subscriber in the list. Note: When you register a new subscriber, you may want that subscriber to install and use the Documentum CDS Client. The Chapter 6, Using the Content Distribution Services Client Application contains more details. Creating groups A group is a name for a list of subscribers. Instead of selecting the subscribers one by one, you select the group. You can use groups for two purposes: Granting access to an offer Sending notifications The predefined Administrator group has special status. Subscribers assigned to the Administrator group have administrative rights to CDS Administrator. You cannot use groups when creating subscriptions. A subscription requires an individual subscriber. Creating groups can simplify the process of adding new offers and subscribers. When you add a new subscriber to a group, the subscriber automatically has access to all the offers for that group. Add a new offer, then update the group definition to grant access instead of having to update all the individual subscriber definitions. Subscribers can subscribe both to offers assigned to them as individuals and those assigned to groups they belong to. If a subscriber is a member of multiple groups, that subscriber can subscribe to any offer available to any of the groups. The procedure below explains how to create a new groups or modify an existing group. The steps are the same in either case. When creating a new group, you must follow the steps in the order they appear. When modifying a group, you can generally skip directly to the step that relates to the item you want to change. You must be logged in as an administrator to create groups. To create or modify a group: 1. Select Groups from the menu. The Groups page appears, showing a list of currently defined groups. The Using list pages, page 25 contains more information on using page to review the existing groups. Documentum Content Distribution ServicesTM Administration Guide 57

58 Registering subscribers 2. Click the Create Group button to define a new group, or click the icon next to the group you want to modify. The Group Info page appears. 3. Enter a name and description of the group. 4. Move to the Attributes page. 5. Enter a category and attributes for the group. Category is set to the default value specified in the CDS Server configuration unless you enter a different value; additional attributes are optional. The Using attributes pages, page 27 contains more information on categories and attributes. 6. Move to the Subscribers page. The list on the left shows all available subscribers; the list on the right shows the current composition of the group you are defining. 7. Select the subscribers and groups that make up this group. The Using selection pages, page 28 contains more information on using this page to select subscribers. If you are modifying the list of users in the Administrator group, make sure not to remove your user name. If you remove yourself from the Administrator group, you will no longer have administrative privileges. 8. Move to the Offers page. 9. Select the offers that this group can subscribe to. Subscribers can subscribe both to offers assigned to them as individuals and those assigned to the group. If a subscriber is a member of multiple groups, that subscriber can subscribe to any offer available to any of the groups. If you skip this step, the subscribers in the group are still able to subscribe to the offers assigned to them in their subscriber definition. Note: If you remove an offer to which any subscribers in this group have a subscription, the subscribers will not receive future updates. The subscriptions are deleted. 10. Click the Finish button to create the group or save your changes. The Groups list page appears with the new group in the list. 58 Documentum Content Distribution ServicesTM Administration Guide

59 Chapter 5 Subscribing to Offers Subscriptions perform the distribution of Content Distribution Services. They link the CDS Server to subscriber s target destinations. Subscribing to an offer involves tasks at both ends of the transaction, the server and the subscriber. Subscriptions define which offers are delivered to which subscribers and how often. Each subscription links one offer to one subscriber. It identifies the address to which the CDS Server delivers the content and delivery schedule. This chapter describes the steps involved in subscribing to an offer: Before you begin, page 59 Creating subscriptions, page 60 Before you begin To create a subscription, you need this information: The name of the offer to which you want to subscribe The user name of the subscriber The protocol to use for delivering offer content to the subscriber For ICE subscribers, the URL of a CDS Client application installed by the subscriber For FTP subscribers, the FTP server and directory for distributing the content, and a user name and password that the CDS Server can use to log in to the FTP server For subscribers, the addresses to which the CDS Server sends the offer content Once the subscription is in place, ICE subscribers need to register the new subscription with CDS Client and specific where in the target repository to deploy the content they receive. The Chapter 6, Using the Content Distribution Services Client Application contains more information. Documentum Content Distribution ServicesTM Administration Guide 59

60 Subscribing to Offers Creating subscriptions Once you have completed the preparatory tasks, you are ready to create a subscription. The procedure below explains how to create a new subscription or modify an existing one. The steps are the same in either case. When creating a new subscription, you must follow the steps in the order they appear. When modifying a subscription, you can generally skip directly to the step that relates to the item you want to change. To create a subscription: 1. Select Subscriptions or Offers from the menu. The Subscriptions list page provides a list of current subscriptions. The Offers list page lists the available offers; if you are logged in as a non-administrative subscriber, only the offers you can subscribe to appear in the list. The Using list pages, page 25 contains more information on using these list pages. Note: To create a subscription from the Offers list page, you must select the offers using the checkboxes to the left of the offer names. Once you have selected the offers, you can click the Preview Subscription button to view what documents comprise the offers. 2. Click the Create Subscription button, or (from the Subscriptions list page) click the icon next to the subscription you want to modify. The Subscription Info page appears. If you are modifying an existing subscription, the page displays the package ID of the most recent package that the CDS Server delivered. The Resolving delivery issues, page 74 contains information on having the CDS Server resend previous packages. 3. Enter a name and description for the subscription. 4. Select the subscriber from the dropdown listbox. The subscriber you select determines which offers are available on the Offers page (step 7). The Subscriber list displays only those subscribers in the category selected from the Category list. If you are logged into CDS Administrator as a subscriber rather than an administrator, only your subscriber name appears in the list. You can only subscribe to offers for yourself. 5. Move to the Attributes page. 6. Enter a category and attributes for the subscription. Category is set to the default value specified in the CDS Server configuration unless you enter a different value; additional attributes are optional. The Using attributes pages, page 27 contains more information on categories and attributes. 7. Move to the Offers page. 60 Documentum Content Distribution ServicesTM Administration Guide

61 Subscribing to Offers 8. Select the offers to subscribe to. The Using selection pages, page 28 contains more information on using this page to select offers. The page displays all offers that the subscriber from step 4 is authorized to subscribe to, that is, those offers linked to the subscriber definition or to any group the subscriber belongs to. If the offer you want does not appear in the list, modify this subscriber s definition to grant access to the offer. The Chapter 4, Registering subscribers contains more information. 9. Move to the Offer Templates page. 10. From the Offer dropdown list, select an offer to which you want to apply templates. 11. Select the templates to apply to the selected offer s content. The Preparing content for delivery: Templates, page 13 contains more information on templates. The Using selection pages, page 28 contains more information on using page to select templates. 12. Set the order in which to apply the templates. If you select more than one template, the CDS Server applies them to the offer content in the order in which they appear in the Selected Templates list. If a template does not appear in the correct position in the list, highlight it and click the Up or Down button to move it. 13. Repeat steps 10 through 12 for each offer in the subscription. 14. Move to the Global Templates page. 15. Select the templates to apply to the subscription as a whole. The template you select on this screen are applied to the contents of the subscription after any offer templates are applied. The Preparing content for delivery: Templates, page 13 contains more information on global templates. The Using selection pages, page 28 contains more information on using page to select templates. 16. Set the order in which to apply the global templates. If you select more than one template, the CDS Server applies them to the offer content in the order in which they appear in the Selected Templates list. If a template does not appear in the correct position in the list, highlight it and click the Up or Down button to move it. 17. Move to the Destination page. Which controls appear on this page depends on the delivery protocol you select. 18. Select the protocol to use for delivering content. The Method box offers these options: ICE Documentum Content Distribution ServicesTM Administration Guide 61

62 Subscribing to Offers FTP 19. Specify the destination for the content. The destination is where the CDS Server delivers the offer content. a. For ICE subscriptions, enter the URL for CDS Client and decide whether to require confirmation from the client. The URL has the form where <web_server> and <port_number> identify the location where the subscriber installed CDS Client. If you select Confirmation Required, the CDS Server waits for the subscriber to confirm the delivery of a package before it sends subsequent packages (the next time the subscription runs). b. For FTP subscriptions, enter the FTP connection information. In the FTP address box, enter the server name and directory where the CDS Server should write the offer content. In the User, Password, and Confirm Password boxes, enter login information so that the server can log in to the FTP server with write access to the specified folder. When you enter the password, asterisks appear in place of the characters you type for security purposes. Note: The directory in the FTP address box is assumed to be a subdirectory of the specified user s home directory. For example, in the illustration below, the CDS Server writes the offer content to the directory /home/guest/catalog, not to a root-level directory /catalog. 62 Documentum Content Distribution ServicesTM Administration Guide

63 Subscribing to Offers c. For subscriptions, enter the header information. Enter the addresses to which the server sends the offer content, the address that appears in the message s From field, and a Subject line. The subscriber s address appears in the To box by default. You can enter multiple addresses in the To and CC boxes, separated by semi-colons. If you do not enter a From name or Subject, the CDS Server uses default information specified during installation. 20. Specify whether to include document metadata as part of the subscription package. Documentum Content Distribution ServicesTM Administration Guide 63

64 Subscribing to Offers If you select the Send metadata checkbox, the CDS Server includes as part of the subscription an XML for each document containing attributes that describe the describe the document. If the checkbox is unselected, the subscription does not include the XML files. The What the CDS Server delivers to subscribers?, page 20 contains more information. When you move to the next page, the CDS Server attempts to verify the destination by connecting to it using the information from step 19. If it fails, a message appears in the message area, and you cannot leave this page without configuring a valid destination. 21. Move to the Schedule page. 22. Schedule the subscription. The subscription schedule determines when (and how often) the CDS Server runs the subscription, which means checking for new offer packages and delivering them if necessary. The Scheduling offers and subscriptions, page 29 contains more details. 23. Move to the Preview page. The Preview page displays information about the documents that are included in this subscription. The format is similar to a list page. 24. Click the Finish button to create the subscription or save your changes. The Subscriptions list page appears with the new subscription in the list. 64 Documentum Content Distribution ServicesTM Administration Guide

65 Chapter 6 Using the Content Distribution Services Client Application The Content Distribution Services Client (CDS Client) is an application that accepts offer content from a CDS Server using the Information and Content Exchange (ICE) protocol and deploys the content to a target repository. The CDS Client runs on the subscriber s Web server. This chapter provides instructions for using CDS Client to perform these tasks: Logging in, page 65 Configuring subscriptions, page 66 Reading notifications, page 68 The Installing Documentum Content Distribution Services contains more information on installing and configuring the CDS Client. The CDS Client user interface has the same basic look as the CDS Administrator. The Chapter 2, Using CDS Administrator contains more information. Logging in To log into the CDS Client: 1. Point your browser to the URL <web_server> is the name of the Web server hosting CDS Client and <port_number> is the port that CDS Client uses. 2. Enter your Content Distribution Services user name and password. The person who installed CDS Client set the user name and password. When you enter the password, asterisks display in place of the characters you type for security purposes. 3. Click Login. The main screen appears. Documentum Content Distribution ServicesTM Administration Guide 65

66 Using the Content Distribution Services Client Application If the login is unsuccessful, a message appears beneath the Login name and Password fields indicating the problem. Correct the problem and try again. If the problem persists, consult your system administrator. Con guring subscriptions Each subscription has a unique Subscription ID that the CDS Server and CDS Client use to identify it. When you subscribe to an offer, you need to register its Subscription ID on CDS Client and specify where in the target repository to save the received content. If CDS Client is installed and running when you or the distributor create the subscription, the CDS Server automatically sends the Subscription ID and preconfigures a few server-related parameters. If CDS Client does not receive the Subscription ID automatically, you need to get the Subscription ID from the distributor and enter it manually; in this case, you also need the URL and Sender ID for the CDS Server. To con gure a subscription: 1. Select Subscriptions from the main menu. The Subscriptions list page appears showing your current subscriptions. New subscriptions that require configuration have information only in the ID column. 2. Click the icon next to the subscription you want to configure. If a new subscription does not appear in the list, click Create Subscription to add it. The Subscription Info page appears. 66 Documentum Content Distribution ServicesTM Administration Guide

67 Using the Content Distribution Services Client Application 3. Enter the Subscription ID from the distributor. If you selected a subscription whose Subscription ID is already available, most of the fields on the page contain the correct values from the CDS Server. Do not change these values. 4. Enter a name and description for the subscription. These values are for your identification purposes only. 5. If the Last package ID box does not already contain a value, enter ICE-INITIAL. 6. If the Server URL box does not already contain a value, enter the URL to which CDS Client sends confirmations to the CDS Server. The distributor needs to provide you with this information. 7. If the Sender ID box does not already contain a value, enter the ID for the CDS Server. The distributor needs to provide you with this information. 8. Click the Target tab or the > button to move to the Target page. 9. Enter the complete path to the place in the target repository where you want to save the offer content. 10. Click the Finish button to save the newly configured subscription. Documentum Content Distribution ServicesTM Administration Guide 67

68 Using the Content Distribution Services Client Application Reading noti cations CDS Administrator enables the distributor to send notifications to subscribers. Notifications may inform you about new offers or scheduled outages or other administrative issues. To read noti cations: 1. Select Notifications from the main menu. The list of notifications appears with the most recent notifications at the top. 2. Click the icon or the sender name to display the message. 3. Click Close when you are done reading the message. 68 Documentum Content Distribution ServicesTM Administration Guide

69 Monitoring Server Processing Chapter 7 Once you have defined and scheduled offers and subscriptions, the CDS Server handles content distribution automatically. Nonetheless, the server administrator needs to monitor system activity and occasionally intervene to correct an issue. This chapter describes a few common tasks required to maintain the CDS Server: Reading the CDS Server log files, page 69 Configuring the CDS Server, page 70 Managing content cache storage, page 73 Resolving delivery issues, page 74 Reading the CDS Server log les The CDS Server records its activity in two log files, a trace log and an error log. The person who installs Content Distribution Services sets the initial locations of the log files. The distinction between the two files is the level of message that appears in them: The trace log, named cds_trace.log by default, shows the details of all logged the CDS Server activity. It includes status messages in addition to ERROR-level messages. The error log, named cds_error.log by default, includes only ERROR-level messages. The CDS log files conform to the log4j standard. The index.html contains more information on the log4j standard. The log file parameters the file names and locations, rollover frequency, message level, and so on are set in the cxflog.properties file on the CDS Server machine. For example, to change the message level from the default INFO to the more detailed DEBUG, open the cxflog.properties file and change the log4j.category.trace setting to this value: log4j.category.trace=debug, stdout, tracefile The next section contains details on updating the cxflog.properties file. Documentum Content Distribution ServicesTM Administration Guide 69

70 Monitoring Server Processing The top of each log file includes basic configuration data about the CDS Server to assist you and Documentum Technical Support in troubleshooting issues: ************************************** Content Distribution Services 5.2 (build_number) Support: DFC Version: 5.1 java.version : java.vm.vendor : Sun Microsystems Inc. java.vm.name : Java HotSpot(TM) Client VM java.home : directory_name java.class.path : list_of_directory_paths file.encoding : Cp1252 os.name : operating_system os.version : OS_version user.name : user_name user.dir : user_directory ************************************** Status messages begin after this header. The format of the messages depends on the settings in cxflog.properties. Con guring the CDS Server The CDS Server configuration settings are set in a series of files in the directory <cds_home_dir>/admin/config. These files contain settings that provide database connection information, specify the location of the content cache, control the format and message level for log files, and set many other configurable options. Most of the system information the installer entered during installation was written to these files. There are three configuration files that you may need to update: cxflog.xml includes settings related to the CDS Server log files cds.xml identifies the location of the CDS Server cache directory, configures the handling of subscriptions, and sets CDS Administrator defaults utility.xml includes the textual templates that the CDS Server uses to notify subscribers about system updates Caution: Do not modify any setting that you do not completely understand. Invalid settings can result in problems running the CDS Server. In general, avoid changing settings in the utility.xml file other than the message text. For the log file settings, change them only if you are familiar with the log4j standard. The CDS Server reads the settings from these files when it starts up. Therefore, any changes you make take effect the next time you start the CDS Server. To change server con guration settings: 1. Shut down the CDS Server. 70 Documentum Content Distribution ServicesTM Administration Guide

71 Monitoring Server Processing 2. Use a text editor to open the configuration file. 3. Change one or more settings in the file. 4. Save the file and close it. 5. Restart the CDS Server. The tables below list common changes to server configuration and identify the configuration settings that controls them. Table 7-1. Commonly updated cx og.xml settings Setting <appender name="tracefile" class="org. apache.log4j.dailyrollingfileappender"> <param name="file" value="${cds.home}/ admin/log/cds_trace.log"/> <appender name="errorfile" class="org. apache.log4j.dailyrollingfileappender"> <param name="file" value="${cds.home}/ admin/log/cds_error.log"/> <appender name="tracefile" class="org. apache.log4j.dailyrollingfileappender"> <param name="file" value="${cds. home}/admin/log/cds_trace.log"/> <param name="datepattern" value=". yyyy-mm-dd"/> <appender name="errorfile" class="org. apache.log4j.dailyrollingfileappender"> <param name="datepattern" value=". yyyy-mm-dd"/> <logger name="trace" additivity="false"> <level value="info"/> What it controls? The location of the trace log. The location of the error log. The date pattern determines the extension used for past trace logs. The date pattern determines the extension used for past error logs. The message level for the trace log file. Value can contain INFO, DEBUG. Documentum Content Distribution ServicesTM Administration Guide 71

72 Monitoring Server Processing Table 7-2. Commonly updated cds.xml settings Setting <outstanding maxretries=num wait=sec draft=msgname> <offer directory=path> <cds defaultcategory= string What it controls? The number of times the CDS Server retries contacting an ICE subscriber, and the number of seconds between each retry. The draft attribute identifies the message (from utility.xml) that the CDS Server sends to request confirmation. The location of the content cache directory. Do not change the resourcegroup attribute. The value entered in the Category box by default. Modifying noti cation messages The CDS Server notifies subscribers in the case of updates or events that affect their subscriptions. The text of the notification messages is set in the file utility.xml. The relevant section of the file is the <messages> element. The <messages> element contains a series of <draft> subelements, each of which represents a CDS Server notification message. The structure of a <draft> is: <draft name=notify_event> <from>address for the from field of the notification</from> <subject>text for the subject line of the notification</subject> <body>text for the body of the notification message</body> </draft> You typically do not want to change the value of the name attribute, which identifies the event that triggers the message. The <from>, <subject>, and <body> elements define the content of the message sent when the event occurs. All three elements are optional, although you must include at least one element: if you omit an element, the CDS Server uses the text from the corresponding element in the <draft> identified as the default for the <messages> element, usually the status draft. The default messages include variables that the CDS Server replaces with the IDs or names of the system objects that triggered the message. You can use these variables in any revised versions of the messages. To change the noti cation messages the CDS Server sends: 1. Shut down the CDS Server. 72 Documentum Content Distribution ServicesTM Administration Guide

73 Monitoring Server Processing 2. Use a text editor to open the utility.xml file. 3. Locate the begin tag for the <messages> element. 4. Locate the <draft> element you want to modify. 5. Update the message text. 6. Save the file and close it. 7. Restart the CDS Server. Managing content cache storage By default, the CDS Server stores the current content of every available offer in the content cache directory. As the number of offers grows, or the number of documents in the offers grows, the disk holding the content cache may run low on disk space. Before the CDS Server runs out of content cache space, you need to move the content cache to a disk with sufficient storage. You can reduce the volume of documents in the CDS Server content cache directory by creating offers with the retrieve content by reference option. This option, which is available for repository offers and file-system offers, creates offers for which the selection query retrieves references to documents in the source repository instead of the documents themselves. The documents are not copied into the cache directory. When a subscription is run for that offer, the CDS Server retrieves the identified documents from the repository and sends them to the subscriber. To move the content cache directory: 1. Shut down the CDS Server. 2. Create a directory for the content cache on a disk with sufficient disk space. 3. Copy the contents of the current content cache directory to the new directory. 4. Use a text editor to open the cds.xml. 5. Change the value of the <offer directory> setting to point to the new content cache directory. 6. Save the file and close it. 7. Restart the CDS Server. Documentum Content Distribution ServicesTM Administration Guide 73

74 Monitoring Server Processing Resolving delivery issues CDS Administrator tracks which packages have been sent to a subscriber by recording the package ID of the most recently sent package as part of the subscription object. The subscription package ID is distinct from the package IDs for the offers that comprise the subscription. If a subscriber needs to re-receive one or more packages for any reason, you can cause the CDS Server to resend packages by resetting the package ID. To reset the package ID for a subscription: 1. Log in to CDS Administrator. The Logging in, page 23 contains more details. 2. Select Subscriptions from the menu. The Subscriptions list page appears. 3. Select the subscription whose package ID you need to reset. The Using list pages, page 25 contains details about selecting a subscription from the list page. The Subscription Info page appears with the details for the selected subscription. The Package ID dropdown list shows the package ID of the last package the CDS Server delivered. 4. From the Package ID dropdown list, select the package ID of the last package the subscriber received properly. To resend the entire contents of the offer, select None. 5. Click Finish to save your update. 6. If the subscriber uses CDS Client to receive content, instruct the subscriber to make sure the package ID that CDS Client records for the subscription is the same as the value on the CDS Server. The subscriber needs to open the subscription using CDS Client and check the value in the Last package ID box. The value should be the same as the value you entered at step 4, except if you entered 0. If you entered 0, the subscriber needs to enter ICE-INITIAL into the Last package ID box. Modi ed offers and subscriptions Changes to offers and subscriptions are inevitable in production environment. This section describes how the CDS Server responds to updates in a few situations where the result might not be what you immediately expect. 74 Documentum Content Distribution ServicesTM Administration Guide

75 Monitoring Server Processing Retrieving content by reference When an offer uses the Retrieve content by reference option, there is a delay between when the CDS Server runs the offer (and creates the offer package using document identifiers) and when it retrieves the documents from the source repository. During this delay, it is possible for the documents in the source repository to change. To illustrate possible scenarios and how CDS handles them, consider an example offer that uses the Retrieve content by reference option. Offer X is scheduled to run once a day. On the first day, the CDS Server runs the offer query, which selects Document A and Document B. The CDS Server creates an offer package containing document identifiers for Document A and Document B. When a subscription to Offer X runs, the CDS Server retrieves the documents identified in the offer package, delivering Document A and Document B to the subscriber. At some point before the offer is run again, someone updates Document B and adds a new document, Document C. When the next subscription to Offer X runs, the subscriber receives Document A and the updated version of Document B. The subscription does not include Document C, because that document is not included in the offer package created when the offer was run. Note: If Offer X delivers content from the Documentum repository, the subscriber receives the updated Document B only if the updated version has the same version number as the original version. If the user checks in Document B as a new version, the CDS Server continues to deliver the original version, which is the document identified in the offer package. If the first subscription, which ran before Document B was updated, runs a second time before the offer runs again, the subscriber does not receive the updated version of Document B. The CDS Server ensures that the subscriber has already received the current package. When the Offer X selection query runs on the next day, the state of the offer is brought back into line with the state of the repository. Modifying templates When you change a template that is already in use, subscribers can see the effect of the change only on content that is delivered to them after the change is saved. The CDS Server does not redeliver documents that the subscriber has already received. For example, suppose a template adds corporate contact information to each document delivered to investment analysts as part of an Investor Relations offer. After the offer and template have been in use for several months, you move to a new location or hire a new director of investor relations and update the template to reflect the change. Documentum Content Distribution ServicesTM Administration Guide 75

76 Monitoring Server Processing Subscribers will view the updated information only on documents delivered to them after the change; documents they received previously continue to show the old contact information. New subscribers, who have not received any documents previously, view the new contact information on all documents, including those that were part of the offer before the template update. If it is important for the template change to apply retroactively to previously delivered documents, you can force the CDS Server to redeliver documents by resetting the package ID for each subscription to the ID of the earliest package you want to resend with the new template. 76 Documentum Content Distribution ServicesTM Administration Guide

77 Appendix A Content Distribution Services Custom JSP Tag Reference Content Distribution Services enables you to apply JavaServer Page (JSP) templates to the content of an offer before delivering it to subscribers. The Preparing content for delivery: Templates, page 13 and Creating templates, page 52 contain more information on using templates. The JSP templates can use any tags from the JavaServer Pages Standard Tag Library or from the Apache Struts framework. In addition, Content Distribution Services supports several custom JSP tags related specifically to content distribution, shown in the table below. To use the custom tags for Content Distribution Services, include this taglib directive in the JSP template file: <%@ taglib uri="/web-inf/cxf-format.tld" prefix="cxf"%> Table A-1. Content Distribution Services JSP Tags Document processing track, page 80 writedocument, page 82 Text processing Tag cleanup Data type processing applyformat, page 78 replacetext, page 79 truncatetext, page 81 stripimages, page 79 striptables, page 80 striptags, page 80 formatdate, page 78 formatnumber, page 79 Documentum Content Distribution ServicesTM Administration Guide 77

78 Content Distribution Services Custom JSP Tag Reference applyformat Searches for a specified string and inserts text before or after it Syntax <cxf:applyformat regexp="regular_expression" [beforetext="before_text"] [aftertext="after_text"] >body_content</cxf:applyformat> Description The applyformat tag searches body_content for strings that match the regular_expression. For each match, it inserts the before_text immediately before the match and the after_text immediately after. Example This example makes the distributor s company name, Rubicon, appear in bold face wherever it occurs by inserting the appropriate HTML tags around the company name. <%@ taglib uri="/web-inf/cxf-format.tld" prefix="cxf" %> <% response.setcontenttype("text/html"); response.setheader( "Syndication-File-Name", com.documentum.util.dateutility.gettime()+".htm" ); %> <cxf:applyformat regexp="rubicon" beforetext="<b>" aftertext="</b>"> <cxf:writedocument name="current"/> </cxf:applyformat> formatdate Formats a date in a specified date format Syntax <cxf:formatdate toformat= to_format_string [fromformat= from_ format_string ]>body_content</cxf:formatdate> Description The formatdate tag converts body_content into a date in the format described by to_format_string. The from_format_string identifies the current format of body_content. The format strings must be standard Java time pattern strings. If the fromformat attribute is omitted, the assumed format is EEE MMM dd kk:mm:ss zzz yyy, which is the default pattern for the Date.toString( ) function. The formatdate tag returns an error if body_content is not in the expected from format. 78 Documentum Content Distribution ServicesTM Administration Guide

79 Content Distribution Services Custom JSP Tag Reference formatnumber Formats text as a number Syntax <cxf:formatnumber>body_content</cxf:formatnumber> Description The formatnumber tag formats body_content as a number in the format ###,###. It returns an error if body_content consists of characters other than numeric digits. Example This example prints the size of the current document. <%@ taglib uri="/web-inf/cxf-format.tld" prefix="cxf" %> <%@ page contenttype="text/plain" %> <% response.setheader("syndication-file-name", com.documentum.util.dateutility.gettime()+".txt"); %> <cxf:formatnumber> <cxf:writedocument name="current" property="size"/> </cxf:formatnumber> replacetext Searches for a specified string and replaces it with another string Syntax <cxf:replacetext fromtext= regular_expression totext= replacement_ string >body_content</cxf:replacetext> Description The replacetext tag searches body_content for strings that match regular_expression. For each match, it deletes the matching string and inserts replacement_string in its place. stripimages Removes image references Syntax <cxf:stripimages>body_content</cxf:stripimages> Documentum Content Distribution ServicesTM Administration Guide 79

80 Content Distribution Services Custom JSP Tag Reference Description The stripimages tag searches body_content for image reference tags (that is, tags that begin with an angled bracket followed by img ) and removes each one it finds. striptables Removes tables from HTML content Syntax <cxf:striptables>body_content</cxf:striptables> Description The striptables tag searches body_content for tags that identify elements of HTML tables and replaces them with corresponding non-table tags. striptags Removes all angle-bracket-style tags Syntax <cxf:striptags>body_content</cxf:striptags> Description The striptags tag searches body_content for tags that appear between angled brackets and removes each occurrence it finds. The result is untagged text. track Adds an element to HTML files for tracking when they are accessed Syntax <cxf:track [id=custom_id]>body_content</cxf:track> Description The track tag embeds a small transparent image into body_content, which must be HTML text. The source URL of embedded image refers to a special the CDS Server service, which records the fact that the document has been accessed. When the body_content is loaded into an end-user s browser, the image causes the browser to contact the CDS Server, which records the event in its event table. By default, the CDS Server records the ID of the subscription that originally delivered the content, the 80 Documentum Content Distribution ServicesTM Administration Guide

81 Content Distribution Services Custom JSP Tag Reference document ID and version. If the id attribute is included, the CDS Server records the custom_id instead of the document and subscription information. Example This example creates a document that will record an event whenever a user opens it in a browser. <%@ taglib uri="/web-inf/cxf-format.tld" prefix="cxf" %> <cxf:track> <cxf:writedocument name="current"/> </cxf:track> truncatetext Truncates a string Syntax <cxf:truncatetext [start=number_of_initial_characters] [end=number_ of_final_characters]>body_content</cxf:truncatetext> Description The truncatetext tag removes characters from the beginning or end (or both) of body_content. It removes the first number_of_initial_characters characters and the last number_of_final_characters characters. If both attributes are omitted, no characters are truncated. Documentum Content Distribution ServicesTM Administration Guide 81

82 Content Distribution Services Custom JSP Tag Reference writedocument Writes the contents or properties of a document Syntax <cxf:writedocument name=document_name [property=property_name] [scope=scope] /> Description Use the writedocument tag to access the content or properties of the document identified by document_name. The name current refers to the current document. If the property attribute is omitted, the writedocument tag writes the document s content. If a specified property can have multiple values, include an array subscript after the property name to indicate which value to retrieve; for example, with this attribute the writedocument tag returns the second value of the writers property: property="writers[1]" The scope attribute identifies where in the program scope the document_name document is stored: the page, request, session, or application. If the scope attribute is omitted, the writedocument tag uses the standard findattribute method to search in everwidening scope until it finds the document. Example The first example prints the contents of a single document. <%@ taglib uri="/web-inf/cxf-format.tld" prefix="cxf" %> <cxf:writedocument name="current"/> The next example prints the contents of all the documents in a package. It iterates through the list of documents and prints each one in turn. This code is appropriate for a template that applies to the package as a whole rather than to individual documents; that is, templates for which the Multiple checkbox is selected during registration. The Creating templates, page 52 contains more information on Multiple option. <%@ taglib uri="/web-inf/struts-logic.tld" prefix="logic" %> <%@ taglib uri="/web-inf/cxf-format.tld" prefix="cxf" %> <logic:iterate id="doc" name="current" property="iterator"> <cxf:writedocument name="doc"/> </logic:iterate> The final example prints the value of a document s primary writers, which is the first name listed in the multi-valued writers property. <%@ taglib uri="/web-inf/cxf-format.tld" prefix="cxf" %> 82 Documentum Content Distribution ServicesTM Administration Guide

83 Content Distribution Services Custom JSP Tag Reference <cxf:writedocument name="current" property="writers[0]" /> Documentum Content Distribution ServicesTM Administration Guide 83

84 Content Distribution Services Custom JSP Tag Reference 84 Documentum Content Distribution ServicesTM Administration Guide

85 Appendix B Attribute File XML Format When a subscription has the Send metadata option selected, the package sent to the subscriber includes an XML file for each item in the subscription, containing attribute information. The file contains metadata that CDS uses when delivering the item, and may also include user-selected attributes from the source repository. The Creating offers, page 36 contains details on how to select which attributes are included. The attribute XML file names match the corresponding content files except for their extension. The attribute files appear in a.cxf subdirectory of the directory containing the content files. The sample file below illustrates the format. <?xml version="1.0" encoding="utf-8"?> <item type="document"> <id>mdkwmdawmdi4mda4zjzmzi0tls0tlq==</id> <name><![cdata[checkin doc]]></name> <version><![cdata[09/05/ :15:44]]></version> <folders> <folder><![cdata[archived]]></folder> </folders> <metadata> <property> <name><![cdata[first_class_docbase_object]]></name> <value><![cdata[true]]></value> </property> <property> <name><![cdata[root]]></name> <value><![cdata[c:/oracle/oradata/localdb]]></value> </property> <property> <name><![cdata[file]]></name> <value><![cdata[c:/oracle/oradata/localdb/temp01.dbf]]></value> </property> </metadata> <attributes> <attribute> <name><![cdata[object_name]]></name> <value><![cdata[checkin 23886]]></value> Documentum Content Distribution ServicesTM Administration Guide 85

86 Attribute File XML Format </attribute> <attribute> <name><![cdata[r_modify_date]]></name> <value><![cdata[09/05/ :15:44]]></value> </attribute> <attribute> <name><![cdata[authors]]></name> <value><![cdata[bob]]></value> <value><![cdata[fred]]></value> <value><![cdata[ginger]]></value> </attribute> <attribute> <name><![cdata[object_type]]></name> <value><![cdata[checkin_notice]]></value> </attribute> </attributes> </item> The structure of the file is described below. The first line of the file identifies it as an XML file. <item> is the root element. The type attribute identifies whether the item being described is a document or a folder. <id> is the internal identifier that the CDS Server uses to identify the item. The values that the CDS Server assigns as the <name> and <version> of the item differs depending on the nature of the source repository. The What the CDS Server retrieves from the repository?, page 18 contains more information. <folders> identifies the location where the item is stored. Each <folder> value is a relative path from the root folder of the offer. The <metadata> element contains internal system metadata. The <attributes> element contains the names and values for any user-selected attributes. Each <attribute> element gives the name and one or more values for an attribute chosen as part of the offer definition. The Specifying the offer query, page 39 contains information on selecting the attributes to include. The <attributes> element is empty if no user-selected attributes are included in the offer. 86 Documentum Content Distribution ServicesTM Administration Guide

87 Index A administrators creating, 55 tasks, 21 architecture, 10 attributes as filter conditions, 43, 52 file format, 85 including in repository offer, 42 including in Site Caching Services offer, 51 C CDS Administrator logging in, 23 using, 24 CDS Client logging in, 65 using, 66 CDS Server basic processing, 17 configuration file, 70 defined, 10 log files, 69 monitoring, 69 changing objects, 26 confirmation requiring from ICE client, 62 content cache location, 72 moving, 73 creating objects, 26 cxflog.properties file, 70 D databases offer queries, 48 selecting content, 19 debugging, 69 deleting objects, 26 delivery protocols, 11 E editing objects, 26 , sending, 33 errors, logging, 69 expiration dates for offers, 37 F File system offer queries, 46 files delivered to subscribers, 20 names, 20 retrieved from repository, 18 Finish button, 24 G global templates, 52 groups, 57 I ICE configuring subscriptions, 66 creating subscriptions, 62 defined, 11 setting target destination, 67 J JSP templates creating, 52 custom tags, 77 defined, 13 Documentum Content Distribution ServicesTM Administration Guide 87

88 Index L log files, 69 logging in CDS Administrator, 23 CDS Client, 65 M menu options for subscribers, 24 modifying objects, 26 Multiple checkbox, 54 N new objects, creating, 26 notifications reading, 68 sending, 33 O objects creating, 26 deleting, 26 modifying, 26 offer templates, 52 offers availability dates, 37 content retrieved, 18 creating, 36 defined, 12 including attributes, 42, 51 preparatory tasks, 35 queries for, 39 resending packages, 74 running off schedule, 27 scheduling, 29 subscriber access to, 14 subscribing to, 60 updating content, 13 P packages defined, 12 resending, 74 resetting IDs, 74 protocols, 11 Q queries creating, 39 for database repositories, 19 R removing objects, 26 renditions, 41, 45 repositories offer queries, 40 S saving, 25 schedules defining, 29 offers and subscriptions, 15 running off schedule, 27 selecting items, 25 selection criteria, 39 sending , 33 server basic processing, 17 monitoring, 69 setup tasks, 21 SQL queries for database repositories, 19 subscribers defined, 14 menu options available, 24 notifying, 33 registering, 55 tasks, 21 subscriptions configuring on CDS Client, 66 creating, 60 defined, 14 preparatory tasks, 59 resending packages, 74 running off schedule, 27 scheduling, 29 T templates creating, 52 custom JSP tags, 77 defined, 13 global, 52 supported types, Documentum Content Distribution ServicesTM Administration Guide

89 Index U users creating, 55 notifying, 33 types of, 20 X XML format of attribute files, 85 Documentum Content Distribution ServicesTM Administration Guide 89