User manual MACROMEDIA CONTRIBUTE 3 - CONTRIBUTE PUBLISHING SERVER

CONTRIBUTE 3 Contribute Publishing Server Trademarks 1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally. Third-Party Information This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites. Opera ® browser Copyright © 1995-2002 Opera Software ASA and its suppliers. All rights reserved. Copyright © 2005 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without written approval from Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation, commercial purposes, such as selling copies of this documentation or providing paid-for support services. Acknowledgments Project Management: Jennifer Rowe Writing: Chris Bedford, Jennifer Rowe Managing Editor: Rosana Francescato Editing: Mary Kraemer, Barbara Milligan, Lisa Stanziano, Anne Szabla Production Management: Patrice O'Neill Media Design and Production: Adam Barnett, Aaron Begley, John Francis, Mario Reynoso Special thanks to Ken Sundermeyer, Eric Lerner, Chris Denend, Joel Huff, Lawson Hancock, Erik Larson, Sheila McGinn, Emilio Passi, Yoko Bayer, Scott Richards, Melissa Baerwald, Deb Galdes, Kimberly Oslob, Dennis Griffin, Jon Varese, Brady Kroupa, Josh Margulis, Gavin Anderson, Deeje Cooley, Vickie Chapman, Kaori McLister, and the Contribute engineering and QA teams. Fourth Edition: July 2005 Macromedia, Inc. 601 Townsend St. San Francisco, CA 94103 CONTENTS CHAPTER 1: Using Contribute Publishing Server . ......................... 5 Accessing the Contribute Publishing Server Console . . . . . . . . . . . . . . . . . . . . . . . . 5 Enabling or disabling E-mail and Log services for a website. . . . . . . . . . . . . . . . . . . 7 Using the Simple File Deployment service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Setting up the Simple File Deployment service . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Accessing and using the Simple File Deployment service . . . . . . . . . . . . . . . . . . 9 Using the RSS Activity Feed service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Setting up the RSS Activity Feed service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Accessing the RSS Activity Feed service file . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Viewing the events log for a website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Changing your CPS Console password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Forwarding website events to a custom service. . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 CHAPTER 2: Extending Contribute Publishing Server . . . . . . . . . . . . . . . . . . . . . 15 15 17 18 19 19 20 22 22 23 24 24 24 24 25 25 25 26 26 26 26 27 27 Contribute Publishing Server API overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a custom publishing service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Write a web service that implements the CPS API . . . . . . . . . . . . . . . . . . . . . . Installing the custom service on a server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing and troubleshooting your custom service . . . . . . . . . . . . . . . . . . . . . . . About extending the Simple File Deployment service . . . . . . . . . . . . . . . . . . . . . . About extending the RSS Activity Feed service . . . . . . . . . . . . . . . . . . . . . . . . . . . API data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Web service methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . adminChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . adminRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cancelInboxEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . changeOwner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . inboxEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . makeDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeDirectory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rollBack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sendForReview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 tempPosting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 undoCheckOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 undoSend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 4 Contents CHAPTER 1 Using Contribute Publishing Server Macromedia Contribute Publishing Server (CPS) is a user management and publishing solution that lets Contribute administrators manage large groups of Contribute users and monitor what those users do on the website. CPS has an administration console that enables you to view settings for the User Directory, Log, and E-mail services, and to view settings for each website you've enabled CPS for. CPS also has the Simple File Deployment and RSS Activity Feed services, which are not available through the console, but you can use them as they are or extend to meet your needs. This chapter contains the following sections: · · · · · · · "Accessing the Contribute Publishing Server Console" on page 5 "Enabling or disabling E-mail and Log services for a website" on page 7 "Using the Simple File Deployment service" on page 8 "Using the RSS Activity Feed service" on page 10 "Viewing the events log for a website" on page 12 "Changing your CPS Console password" on page 13 "Forwarding website events to a custom service" on page 14 Accessing the Contribute Publishing Server Console The Contribute Publishing Server (CPS) Console enables you to configure the User Directory service, specify an SMTP mail server to use with the E-mail Notification service, and configure the Log service settings. You can also use the console to configure your CPS settings for your website. You can access the console from Contribute, or from an external web browser. Note: The CPS Console requires that you have Flash Player 7 installed on your computer. 5 To access the CPS Console from Contribute: 1. In Contribute, select Edit > Administer Websites (Windows) or Contribute > Administer Websites (Macintosh), and then select the website you want to administer from the submenu. If the website has no administrator, click Yes when a dialog box asks whether you want to become the website administrator. Then enter and confirm an administrator password for the website, and click OK. The Administer Website dialog box appears. 2. Select the Publishing Server category from the list on the left. The Publishing Server options appear. 3. Click the Publishing Server Console link. The Log In dialog box appears. 4. Enter the CPS administrator password, and then click Login to log in to the CPS Console. The Website Settings options of the CPS Console appear. To access the CPS Console from a web browser: 1. In a web browser, enter the URL for the CPS Console. The URL for the CPS Console is https://hostname:port/contribute/admin/server.cfm, and uses the following variables: hostname port is the server computer's DNS name or IP address. is the network port number used by the CPS. Tip: If you used the CPS Simple Installation (the version that includes a pre-configured Java application server) the URL for the CPS Console is https://localhost:8900/contribute/admin/. If you used the CPS WAR File Installation within an existing Java application server, the port number will vary with your application server's configuration The Log In dialog box appears. 2. Enter the CPS administrator password, and then click Login to log in to the CPS Console. The Overview section of the CPS Console appears. 6 Chapter 1: Using Contribute Publishing Server Tip: To easily open the CPS Console, try adding a bookmark in your browser. Enabling or disabling E-mail and Log services for a website You can enable or disable the E-mail and Log services for any website you've enabled Contribute Publishing Server (CPS) for. The E-mail service automatically sends e-mail messages to users notifying them status of drafts sent for review. The Log service monitors website activity. If you want to disable the User Directory service for a website, you need to do so from Contribute. For more information, see Administering Contribute in Contribute Help. To enable or disable the E-mail or Log service: 1. Open the CPS Console (see "Accessing the Contribute Publishing Server Console" on page 5). The CPS Console appears. 2. If the Website Settings options are not showing, select Website Settings from the Service Settings list on the left. The Website Settings options appear in the CPS Console. 3. Select a website from the Website pop-up menu. 4. For the E-mail service, select or deselect the following options: The Notify users when they receive a draft for review option sends an e-mail message when a user receives a draft for review. The Notify users when their sent drafts change in status option sends an e-mail message when a user's draft change status. 5. For the Log service, select or deselect the Maintain a log of website changes check box. 6. Click Save Settings to save your settings. Enabling or disabling E-mail and Log services for a website 7 Using the Simple File Deployment service Contribute Publishing Server (CPS) provides an extensible framework for a Simple File Deployment service that you can modify to meet your needs for moving files from a staging or testing server to a live server. You can use the compiled version of this service as is, but it is intended to be a starting point for you to extend the functionality for your specific needs. You can extend the uncompiled version of the service. Note: For information about extending the service, see "About extending the Simple File Deployment service" on page 20. Whether you extend the service or decide to use it as is, you should complete the set-up tasks before you start using the service. Setting up the Simple File Deployment service Before you use the Simple File Deployment service, you need to complete some set-up tasks. Note: If you extended the service, you might not need to complete all the set-up steps, but you should review the set-up procedure to make sure you complete any necessary steps for your implementation. After you complete the set-up tasks, you can start using the service to move files from your staging server to your live server. To set up the Simple File Deployment service: 1. Open the settings.xml file, which is located in the following directory: C:/Program Files/Macromedia/Contribute Publishing Server/jrun4/servers/ contribute-wps/contribute/customservices/filedeployer Note: If you plan to extend the service, open the settings.xml file for the uncompiled version of the code in C:/Program Files/Macromedia/Contribute Publishing Server/jrun4/servers/contributewps/contribute/customservices_code/filedeployer. 2. In the settings.xml file, add the URI (web addresses) and FileSystemPath for the staging and live servers for each website you want to use this service, and then save and close the file. Note: The staging server URI must match the web address (URL) of a website you've connected to in Contribute for the event notifications to work properly between Contribute and the Simple File Deployment service. For example: http://contribute-staging/teamwebsite c:\\contributestaging\teamwebsite http://contribute.macromedia.com/teamwebsite \\contribute\teamwebsite 8 Chapter 1: Using Contribute Publishing Server 3. Make sure that your server is running with a user that has sufficient network permissions to copy files on the staging and live servers. If you are using Windows, many servers run, by default, with the local system user (which probably has limited network access). To change a server's user on Windows, do the following: a Right-click My Computer, and then select Manage. The Computer Management dialog box appears. b Expand the Services and Applications node, and then select Services. c In the right pane, double-click Macromedia Contribute Publishing Server. The Properties dialog box appears. d Select the Log On tab, and then select the Select this Account option. e Enter your user name and password, and then click OK. The user name and password you enter must have permission to copy files between the staging and the live servers. 4. Now you need to forward client notifications to your Simple File Deployment service, so that the service knows about publish, delete, and roll back actions that occur on the website. Complete the procedure in "Forwarding website events to a custom service" on page 14, and then return to this procedure. 5. Synchronize your staging and live servers. The file structure and content on your staging and live servers must match exactly before you can start using the Simple File Deployment service. 6. Now you can start using the Simple File Deployment service (see "Accessing and using the Simple File Deployment service" on page 9), or you can extend the service before you use it (see "About extending the Simple File Deployment service" on page 20). Note: Macromedia recommends that you extend the functionality of this service; you should at least add authentication functionality before you use it. Accessing and using the Simple File Deployment service After you set up the Simple File Deployment service (see "Setting up the Simple File Deployment service" on page 8), you can start using the service to move files from your staging server to your live server. Note: This procedure is for using the service as is. Macromedia recommends that you extend the service to meet your specific needs (see "About extending the Simple File Deployment service" on page 20). If you extend the service, you should modify the steps for accessing and using the service accordingly. Using the Simple File Deployment service 9 To access and use the Simple File Deployment service: 1. In a browser, enter the address for the Simple File Deployment service. The default install path is https://server:8900/contribute/customservices/ filedeployer/. The Simple File Deployment service shows a list of files that have been published, deleted, or rolled back on the staging server. 2. Select the check box beside each file you want to deploy to the live server. Tip: Click the Select All button to select all the files at once. You can click the Deselect All button if you decide that you don't want to deploy all the file changes. The following icons indicate the type of change made to the file on the staging server. Icon Change to file Published Deleted Rolled back to a previous version 3. Click the Deploy button to deploy the selected file changes to the live server. Contribute updates your live server with the new files. Using the RSS Activity Feed service Contribute Publishing Server (CPS) provides an RSS Activity Feed service that adds a syndication feed to your website to report changes that occur on the website. The RSS Activity Feed service converts Publish, Delete, and Roll Back events into a syndication feed based on the Atom specification. Atom is an XML-based web content and metadata syndication format that creates lists of information, or feeds. Feeds contain a number of items, or entries, and are typically viewed with a news reader or aggregator. Note: For more information on the Atom specification, see www.atomeanbled.org. Changes to pages in specified folders on your websites appear as individual entries in the syndication feed. You can use this information to monitor activity on your websites managed by CPS. To use the service, you need to perform some set-up tasks, and then use a news reader or aggregator to view the output from the service. Note: You can use the compiled version of this service as is, or you can extend the uncompiled version to meet your specific needs. For information about extending the service, see "About extending the RSS Activity Feed service" on page 22. 10 Chapter 1: Using Contribute Publishing Server Setting up the RSS Activity Feed service The RSS Activity Feed service produces a syndication feed that lists Publish, Delete, and Roll Back events that occur to pages in any folder on your website. Before you use the RSS Activity Feed service, you need to complete some set-up tasks. To set up the RSS Activity Feed service: 1. Open the settings.xml file, which is located in the following directory: C:/Program Files/Macromedia/Contribute Publishing Server/jrun4/servers/ contribute-wps/contribute/customservices/rssfeed Note: If you plan to extend the service, open the settings.xml file for the uncompiled version of the code in C:/Program Files/Macromedia/Contribute Publishing Server/jrun4/servers/contributewps/contribute/customservices_code/rssfeed. 2. In the settings.xml file, add the following information for a syndication feed: Name is the name of the syndication feed you're creating. is the server location of the output file the syndication feed creates. TargetPath You need to have HTTP access to this location. WatchURI indicates the folder the RSS Activity Feed service monitors for changes. Any Publish, Delete, or Roll Back events that occur to pages in this folder, or any subdirectory, produces an entry in the syndication feed. Note: If a page belongs to multiple syndication feeds, each syndication feed reports that page's changes. MaxEntries is the upper limit for the number of entries the syndication feed stores. The default value is 20,000. For example: My Site's Announcement \\myserver\wwwroot\feeds\announcementsfeed.xml http://myserver/announcements 25 3. (Optional) Add entries to create other syndication feeds to the settings.xml file if you want. 4. Make sure that your server is running with a user that has sufficient network permissions on the server indicated in the TargetPath to create the syndication feed output file. If you are using Windows, many servers run, by default, with the local system user (which probably has limited network access). To change a server's user on Windows, do the following: a Right-click My Computer, and then select Manage. The Computer Management dialog box appears. b Expand the Services and Applications node, and then select Services. Using the RSS Activity Feed service 11 c In the right pane, double-click Macromedia Contribute Publishing Server. The Properties dialog box appears. d Select the Log On tab, and then select the Select this Account option. e Enter your user name and password, and then click OK. The user name and password you enter must have permission to copy files between the staging and the live servers. 5. Now you need to forward client notification to your RSS Activity Feed service, so that the service knows about publish, delete, and roll back actions that occur on the website. Complete the procedure in "Forwarding website events to a custom service" on page 14. 6. Now you can use a news reader or aggregator to view changes recorded by the RSS Activity Feed service. Accessing the RSS Activity Feed service file After you set up the RSS Activity Feed service (see "Setting up the RSS Activity Feed service" on page 11), the service reports activity on your website, including Publish, Delete, and Roll Back events in specified folders. You can use a news reader or aggregator, such as the one in Macromedia Central, to view your syndication feed. To install Macromedia Central to access the RSS Activity Feed service file: 1. Download Macromedia Central from the Downloads page on the Macromedia website at www.macromedia.com. When the installation is complete, Central launches. 2. Click the BlogReader button at the top of the Central window to open the BlogReader application. 3. Click the Preferences button to add the RSS Activity Feed service to the BlogReader. 4. When you complete the setup, you can use the BlogReader to view output from the RSS Activity Feed service. Note: There will not be any output to view until an event occurs in Contribute. Related topics · "About extending the RSS Activity Feed service" on page 22 Viewing the events log for a website The Log service maintains an events log of website activity so that you can more easily troubleshoot problems, and so you can see how many users actively update content on the website. Note: If you have not enabled the Log service for your website, see "Enabling or disabling E-mail and Log services for a website" on page 7. 12 Chapter 1: Using Contribute Publishing Server The log file is written to the following directory: C:\Program Files\Macromedia\Contribute Publishing Server\jrun4\servers\default\contribute\WEBINF\pubserver\sites\siteID\logs\events.log Where siteID is an identifier assigned to each site. To view the events log for a website: 1. Open the CPS Console (see "Accessing the Contribute Publishing Server Console" on page 5). The CPS Console appears. 2. If the Website Settings options are not showing, select Website Settings from the Service Settings list on the left. The Website Settings options appear in the CPS Console. 3. Select a website from the Website pop-up menu. 4. Click the View Log button. An event log for the website you selected appears. Tip: Select an option from the Show pop-up menu to filter the log information. 5. When you finish viewing the log, close the web page. Changing your CPS Console password You can change the Contribute Publishing Server (CPS) Console password at any time. The password is for logging in to console; it is not specific to any website connection. Be sure to record your password somewhere so you don't forget it. Tip: If you forget your password, open security.xml in C:/Program Files/Macromedia/Contribute Publishing Server/jrun4/servers/contribute-wps/contribute/WEB-INF/pubserver/server/. Remove the content between the password_hash tags and the salt tags, and then save and close the file. Restart your server, and then you can access the CPS Console without a password so you can set a new password. To change your CPS password for a website: 1. Open the CPS Console (see "Accessing the Contribute Publishing Server Console" on page 5). The CPS Console appears. 2. Click the Change Password link at the bottom. The Change Password dialog box appears. Note: The password is not website-specific, so it doesn't matter which website is selected when you click the Change Password link; you are changing the password for the console. 3. Enter your old password and new password, and then confirm your new password. 4. Click OK to close the Change Password dialog box. 5. Close the CPS Console. Changing your CPS Console password 13 Forwarding website events to a custom service After you write and install a custom service, or after you set up the Simple File Deployment or RSS Activity Feed service, you need to configure the Forwarding service to send events for each website to the new service. You can stop forwarding events at any time. To configure the Forwarding service to send events to another service: 1. Open the CPS Console, if it's not already open (see "Accessing the Contribute Publishing Server Console" on page 5). The CPS Console appears. 2. If the Website Settings options are not showing, select Website Settings from the Service Settings list on the left. The Website Settings options appear in the CPS Console. 3. Select the website you want to use this service from the Website pop-up menu. 4. Click the Other Services tab. The Other Services options appear. 5. Do either of the following: To start forwarding website events to a custom service, click the Add button, enter the URL for your service in the Add Forwarding Service dialog box, and then click OK. Tip: The URL for the Simple File Deployment service is: https://localhost:8900/contribute/ customservices/filedeployer/events.cfm. The URL for the RSS Activity Feed service is: https:// localhost:8900/contribute/customservices/rssfeed/events.cfm. To stop forwarding website events to a custom service, select the URL in the Service URL list, and then click the Delete button above the list. Note: If you're using an Secure Sockets Layer (SSL) server, you need to import the server's certificate to the CPS certificate store. 6. Click Save Settings to save your settings. Related topics: · "Creating a custom publishing service" on page 17 · "Setting up the Simple File Deployment service" on page 8 · "Setting up the RSS Activity Feed service" on page 11 14 Chapter 1: Using Contribute Publishing Server CHAPTER 2 Extending Contribute Publishing Server Macromedia Contribute Publishing Server (CPS) includes logging, e-mail notification, and user management services. There are also two other services that you can use as they are, or you can extend to meet your needs. Using the CPS API, you can extend an existing service, or you can write custom services to add more server-side functionality. This chapter contains the following sections: · · · · · · "Contribute Publishing Server API overview" on page 15 "Creating a custom publishing service" on page 17 "About extending the Simple File Deployment service" on page 20 "About extending the RSS Activity Feed service" on page 22 "API data types" on page 22 "Web service methods" on page 23 Contribute Publishing Server API overview Contribute Publishing Server has components of a server application that run on a server. When you enable a website to use CPS, you specify the address of this server. This instructs all the Contribute clients that interact with that website to send a stream of event data to CPS. These events (editing, publishing, sending for review, and so on) represent users' actions and are transmitted as Simple Object Access Protocol (SOAP) web service messages. CPS is built on these events. For example, the Logging service logs the event data to a file on the server, and the E-mail Notification service e-mails users about pages sent for review. The User Directory service uses a separate web service API for extending how Contribute selects, authenticates, and retrieves connections for users. 15 Note: Custom services are supported through the Forwarding service, which passes along the event data through additional web service invocations. An Example Publish Event Contribute Website Contribute Publishing Services 1 Contribute publishes a page to website. Website E-mail Service and Log Service CPS Server 2 Contribute sends publish event to CPS server. 3 CPS server sends event to CPS services for the website. 4 Forwarding Service sends event to custom services. Simple File Deployment Service RSS Activity Feed Service Your Custom Service Figure 1. How a publish event is posted to CPS and forwarded to a custom service. Contribute sends events after an operation completes. As much as possible, a single user interface operation results in a single event. If multiple files are published when a user clicks the Publish button, Contribute sends a single event but describes all files. If a user interface event affects multiple websites, Contribute sends a single event for each website that is configured to receive events. The CPS API has a method for each type of event. Every type of event has a location and a user, defined as follows: · Location describes the site, URI, and file path related to the event. · User describes the username and e-mail of the user who caused the event. Some events provide additional information, such as dependent files published along with a page or users who were sent a draft for review. Note: Timestamps are not included because the server can easily use its own time when the event is received. 16 Chapter 2: Extending Contribute Publishing Server Related topics: · "About extending the Simple File Deployment service" on page 20 · "API data types" on page 22 · "Web service methods" on page 23 Creating a custom publishing service The Contribute Publishing Server (CPS) API enables you to write custom services to add more server-side functionality. For example, with the CPS API you can make the following types of server-side capabilities possible: · Logging changes to a database for auditing You can write a server-side script to record all site activity against an inventory database. · Automated page-checking at the time of publication You can write a script to check content before it's published. Checks might include compliance with standards, such as Section 508, or broken links. · Setting file permissions You can write a script to reset the permissions of newly written files so that all members of a department can edit them after they are published. · Indexing content You can write a script to index published content for searching. Or, you might want a script to maintain an index for the title, author, or date of documents. · Enhancing the draft review process You can write a server-side script to create more detailed reports or to trigger more e-mail notifications, such as one that might alert a reviewer that a draft has been waiting for review for a specified amount of time. Note: If you want to create a service to move files from a staging/testing server to a live/production server, you can extend the Simple File Deployment service. For more information, see "About extending the Simple File Deployment service" on page 20. CPS sends events to services using the SOAP format over HTTP or HTTPS. A custom service is implemented as a web service, with a web service method for each method of the CPS API. To create a custom publishing service: 1. Write a web service that implements the CPS API. See "Write a web service that implements the CPS API" on page 18. 2. Install the custom service on an application server that CPS can access. See "Installing the custom service on a server" on page 19. 3. Configure the CPS Forwarding service to send events for each website to your custom service. See "Forwarding website events to a custom service" on page 14. 4. Test and troubleshoot you implementation. See "Testing and troubleshooting your custom service" on page 19. Creating a custom publishing service 17 Related topics · · · · "Contribute Publishing Server API overview" on page 15 "About extending the Simple File Deployment service" on page 20 "API data types" on page 22 "Web service methods" on page 23 Write a web service that implements the CPS API The first step in creating a custom service for CPS is to write a web service that implements the CPS API. You can write the service in any language that supports web services, such as Macromedia ColdFusion MX. Note: CPS is supported by ColdFusion MX 6.1 and later. CPS comes with some example and adapter files that might help you write your service. Examples CPS includes examples written in ColdFusion, Java, Perl, and ASP.NET. The example shows a simple logging service (a less complex version of the CPS Log service). Examples for the CPS Simple Installation are located at: C:\Program Files\Macromedia\Contribute Publishing Server\jrun4\servers\contributewps\contribute\customservices_code\simplelogger Examples for the CPS WAR File Installation are located at: C:\Program Files\Macromedia\Contribute Publishing Server\customservices_code\simplelogger For each language, the example includes the web service implementation called MacromediaContributeNotificationService. This implements all the events in the API with a call to an EventLogger component. You can reuse this example by replacing the call to the EventLogger with your own code. Adapters ColdFusion components (CFCs) provide an easy way to implement a web service. However, Macromedia ColdFusion MX 6.1 requires you to use an adapter ColdFusion Markup Language (CFML) file to permit the correct processing of Contribute events. The example ColdFusion service already includes this adapter. Adapter CFML files for the Simple Installation of CPS are located at: C:\Program Files\Macromedia\Contribute Publishing Server\jrun4\servers\contributewps\contribute\customservices\cfmx_adapter\ContributeService.cfm Adapter CFML files for the WAR File Installation of CPS are located at: C:\Program Files\Macromedia\Contribute Publishing Server\customservices\cfmx_adapter\ContributeService.cfm 18 Chapter 2: Extending Contribute Publishing Server To use the adapter file, place a copy of it in the same directory as the CFC file you wish to adapt, and then rename the CFML file to match the CFC filename. For example, to adapt CustomService1.cfc, copy the ContributeService.cfm file into the folder that contains the CFC, and then rename it to CustomService1.cfm. Be sure to use CustomService1.cfm for the URL of the web service instead of the CFC. Related topics · "Creating a custom publishing service" on page 17 Installing the custom service on a server After you write your custom service for CPS, you are ready to install the service on a server that CPS can access. Note: If you have not already written your custom service, see "Write a web service that implements the CPS API" on page 18. Macromedia recommends that you install the custom service on the same physical computer as CPS, for optimal performance. This reduces the time it takes to execute the web service invocation. And also, with both applications on the same computer, you can use the HTTP protocol. HTTP isn't encrypted and is faster than HTTPS--which is the protocol you'd have to use to protect the security of event data if the applications were on two computers. Note: If you decide to install your custom service on a different computer and use SSL to secure the connection, be aware that the Simple Installation of CPS is configured not to trust self-signed certificates. To deploy the example ColdFusion service, install ColdFusion on the server running CPS, and then copy the "cf " folder from the examples to the ColdFusion web root. Tip: If you don't have ColdFusion, you can download a fully functional trial version from the Downloads page on the Macromedia website at www.macromedia.com. Related topics · "Creating a custom publishing service" on page 17 Testing and troubleshooting your custom service After you implement your custom service for CPS, you need to make sure it works. To see if your custom service is working, or to check errors, there are two logs you can use: · The log generated by the CPS Log service For more information, see "Viewing the events log for a website" on page 12. · The CPS Error Log For more information, see "Viewing the CPS Error Log" on page 20. Related topics · "Creating a custom publishing service" on page 17 Creating a custom publishing service 19 Viewing the CPS Error Log You can view the CPS Error Log to see errors that occur when CPS starts or when CPS invokes the Log service, E-mail Notification service, or a custom service. The log is located in the following locations: · For the Simple Installation of CPS: C:\Program Files\Macromedia\Contribute Publishing Server\jrun4\servers\contribute-wps\contribute\WEBINF\pubservices\logs\error.log · For the WAR File Installation of CPS: C:\Program Files\Macromedia\Contribute Publishing Server\WEBINF\pubservices\logs\error.log To view the CPS Error Log from the CPS Console: 1. Open the CPS Console (see "Accessing the Contribute Publishing Server Console" on page 5), if it is not already open. 2. Click the About link at the bottom of the panel. The About dialog box appears. 3. Click the Server Logs link at the bottom of the dialog box. The Server Logs dialog box appears. 4. Select Notification Server Error Log from the pop-up menu. A list of errors appears. 5. When you are finished viewing the log, click Close. About extending the Simple File Deployment service You can use the Simple File Deployment service as a starting point for creating a service that meets your specific needs for moving files from a staging or testing server to a live server. You can use the uncompiled version of the Simple File Deployment service code to extend the service. This code is written in ColdFusion, so you need to have a ColdFusion server to extend this service. Note: CPS installs a special version of the ColdFusion server, which enables you to run the compiled version of the Simple File Deployment service as is. This server, however, is not sufficient for extending the service. You must have the full version of the ColdFusion server running to extend the uncompiled code. When you extend this service, consider adding the following functionality: · Authentication and permissions You can add authentication functionality to limit access to the service. Tip: Macromedia strongly recommends that you add authentication. To do so, you can simply copy the settings file and save it as a separate service in a subfolder for each website, or you can write you own security interface to handle multiple websites. 20 Chapter 2: Extending Contribute Publishing Server