Creating a Custom Contribute Publishing Service

Custom Services

Use the following steps to create a custom publishing service.

1. Create a web service that implements the CPS event API.

Note: The event API docs (SWF, 181K) have been updated with corrections since Contribute 3 shipped. Also, this article completely replaces the readme instructions in the sample services.

You write the service in any language that supports web services, such as Macromedia ColdFusion or Macromedia JRun. The CPS server includes an example for ColdFusion, Java (JRun), Perl, and ASP.NET. These are located at:

• Simple installation:

  {install directory}\jrun4\servers\contribute-wps\contribute\customservices\samples

• WAR file installation:

  {deployment directory}\customservices\samples

The example is a simple logger service, not to be confused with the more sophisticated logging service that comes with the CPS server. For each language, the example includes the web service implementation called MacromediaContributeNotificationService. This implements all of the events in the API with a call to an EventLogger component. You can reuse this example for your own service by replacing the call to the EventLogger with your own code.

Special note for ColdFusion: ColdFusion components (CFCs) are perhaps the easiest way to implement a web service. However, ColdFusion MX 6.1 requires you to use an "adapter" CFML  file to permit the correct processing of Contribute events. This file is located at:

• Simple installation:

  {install directory}\jrun4\servers\contribute-wps\contribute\customservices\cfmx_adapter\ContributeService.cfm

• WAR file installation:

  {deployment directory}\customservices\cfmx_adapter\ContributeService.cfm

This adapter file is easy to use. Place a copy of it in the same directory as the CFC file you wish to adapt and rename the CFML file to match the CFC file name (except for the extension). For example, to adapt CustomService1.cfc, copy the above ContributeService.cfm file into the CFC’s directory and rename it to CustomService1.cfm. Then, ensure that you use CustomService1.cfm for the URL of the web service instead of the CFC.

The example ColdFusion service already includes this adapter.

Note: Contribute Publishing Services is only supported by ColdFusion MX 6.1 and later.

2. Deploy/install the web service on an application server that the CPS server can access.

This step states the obvious. The CPS server must be able to access the web service you create in step one. The point to make clear is that the CPS server application does not run custom services. The custom services must run on a separate application server instance (even if they are implemented in Java or ColdFusion). However, this separate application server may live on the same physical machine as the CPS server, and in fact Macromedia recommends this for optimal performance.

For example, if you have implemented a custom service in ColdFusion, you should install ColdFusion on a different port of the same machine as the CPS server. In Figure 1, see the a CPS server installed on port 8900 (the default for the simple install), and a ColdFusion server installed on the same machine on port 8500 (the default for the CF built-in web server), as indicated by the use of the "http://localhost:8500" URL for the custom ColdFusion service.

The performance benefits of installing the custom services application server on the same machine as the CPS server are twofold. First, it reduces the time it takes to execute the web service invocation. Second, since it is the local machine, you can use the unencrypted and faster HTTP protocol rather than HTTPS, which would otherwise be necessary to protect the security of the event data passed over the network. If you wish to host your custom service on a different machine and use SSL to secure the connection with it, please note that the simple CPS installation is by default configured not to trust self-signed certificates.

To deploy the example ColdFusion service, install ColdFusion on the CPS server and copy the "cf" folder from the samples directory to the ColdFusion web root. If you don't own ColdFusion, you can download and install the fully functional trial version.

3. Configure the Forwarding service for each website to send events to the web service

Unlike the other out-of-box services, which you can configure through the CPS console, the Forwarding service requires that you edit an XML configuration file. Each website has its own XML configuration file on the CPS server.

Use these steps for each site that you wish to forward events to the custom service.

3.1. Look up the website ID.

• Go to the Website Settings panel of the CPS console, as shown in Figure 2.
• Select the website in the Website pop-up menu.
• Position the pointer over the pop-up menu as shown in Figure 2.  
• A tooltip appears with the ID of the website in parentheses. For example, "site123456" .

Figure 2. A Website tooltip for the Contribute Publishing Services Website Settings category

3.2. Find the website folder under

• Simple installation:

  {install directory}\jrun4\servers\contribute-wps\contribute\WEB-INF\pubservices\sites\{website ID}

• WAR file installation:

  {deployment directory}\WEB-INF\pubservices\sites\{website ID}

3.3. Edit the settings.xml file in the website folder and look for the <forward> node. Initially it should look like the following:

<forward>
    <services/>
</forward>

3.4. Add an entry for each custom service you wish to forward events to under the <services> node as follows:

<forward>
   <services>
       <service>
           <url>{url to the custom web service}</url>
       </service>
   </services>
</forward>

For example, to configure the sample ColdFusion service, assuming you copied the "cf" folder to the ColdFusion web root on port 8500, it would look like the following:

<forward>
   <services>
       <service>
           <url>http://localhost:8500/cf/MacromediaContributeNotificationService.cfm</url>
       </service>
   </services>
</forward>

Multiple custom services would look like the following:

<forward>
   <services>
       <service>
           <url>http://localhost:8500/CustomService1.cfm</url>
       </service>
       <service>
           <url>http://localhost:8500/CustomService2.cfm</url>
       </service>
   </services>
</forward>

3.5. Optionally, limit the types of events and event locations that are forwarded to the service.

The <service> node may contain optional child nodes the describe how to filter events to be forwarded.

Events filter: The <events> node text may contain a comma-delimited list of event types. If present, only these events will be forwarded to the service. If absent or empty, all event types will be forwarded. The event type names are their names in the API. For example, publish, changeOwner, and makeDirectory.

Path filter: The <path> node text may contain a single URL that points to a directory or specific file in the website. This URL must be relative to the website root URL. That is:

• if the website URL is http://siteA.company.com/
• and it has a directory http://siteA.company.com/news/
• the root-relative URL to the news directory is news

If present, only events that have a location itemURI that is at or beneath this URL will be forwarded. If absent or empty, all event locations will be forwarded. See the API docs for more information on event locations.

For example, to only forward publish, delete, and rollback events from the news section of your website to the sample ColdFusion service, the service entry would look like the following:

<service>
  <url>http://localhost:8500/cf/MacromediaContributeNotificationService.cfm</url>
  <events>publish,delete,rollback</events>
  <path>news</path> 
</service>

4. Restart the CPS server application.

On the "simple" CPS installation on Windows, you may restart the CPS by opening the Services control panel, selecting the Macromedia Contribute Publishing Services service, and clicking the Restart Service button.

Figure 3. Restarting the Contribute Publishing Services service in the Windows services list

To restart the Contribute Publishing Service on Linux or Solaris, use the following command: cd /[app folder]/bin; stopCPS.sh; startCPS.sh

5. Verify that the custom service is working as expected by interacting with the website in Contribute.

If you are using the sample EventLogger service, you may view the log contents by accessing the sample service directory in a browser, for example, http://localhost:8500/cf/, and clicking Check Log. The log contains XML that describes the raw data for each event.

Page 3 of 4

Previous Page

Next Page