IBM Workplace Web Content Management is a powerful tool used to generate, to store, and to serve content. Syndication is an integral part of the product, enabling you to move content from one Workplace Web Content Management instance to another. This article describes how syndication in Workplace Web Content Management V6 and earlier works and provides tips on how to configure syndication in your implementation.

Syndication in Workplace Web Content Management is based on the Information and Content Exchange (ICE) protocol, an XML-based protocol using HTTP as its transport mechanism. The ICE protocol defines a standard for establishing and managing data exchange between two entities or parties. It is meant to be straightforward and compact, keeping protocol overhead to a bare minimum.

ICE implements a client-server architecture with a supplier and a consumer. The supplier, or syndicator, acts as a kind of master. Changes in its dataset are packaged and sent to the consumer, or subscriber. The subscriber receives the packages, and after validation, applies them to its own dataset. The (trusted) relationship between the syndicator and the subscriber is called a subscription (see figure 1). Generally, a subscription is established by exchanging keys for authentication and authorization. Based on the account details, the subscriber receives a catalog from the syndicator with the available subscriptions.

In most cases, the subscriber is set up to subscribe to a specific subscription. Syndicator and subscriber then negotiate a set of parameters (for example, delivery times and protocol) and establish a subscription.

Payloads

Within a subscription, the syndicator assembles payloads that are consumed by the subscriber (as in figure 1). Payloads are XML documents formatted according to the ICE protocol definition. They contain requests, responses, and so-called unsolicited messages that facilitate a mechanism to implement a so-called minimal subscriber. (In a minimal subscriber implementation, only the subscriber can initiate requests).

Every logical operation in the ICE protocol follows a request/response model. An operation starts with a sender issuing a request, which is sent to the receiver using an HTTP post. The request is answered in a response, which is sent in an HTTP response to that HTTP post.

The ICE protocol is a fully symmetrical protocol in that both syndicator and subscriber can be a sender or receiver and can initiate a logical operation (except the above-mentioned minimal subscriber implementations).

Responses and requests are specified in the payload by use of <ice-response> and <ice-request> XML elements as shown in these code listings:

Request:
	<ice-payload>
		<ice-request>
			Get Package
		</ice-request>
	</ice-payload>
Response:
	<ice-payload>
		<ice-response>
			Package: 42908403985
		</ice-response>
	</ice-payload>

Payloads can contain multiple <ice-request> or <ice-response> elements, but they are always homogeneous; that is, a payload cannot contain a mix of <ice-request> and <ice-response> elements. Also, an <ice-response> in a responding payload should always match the <ice-request> in an initiating payload. If this is not the case, the receiver generates an error.

Back to top

Packages

The actual transfer of data is handled through packages. Packages can be described as a kind of wrapper around the actual data containing identifiers and instructions.

In a subscription, the syndicator creates a list of packages in a specific order (see figure 2). The order is crucial for the subscriber because it must process the packages in the order supplied by the syndicator. To do this, the subscriber maintains a collection that contains the packages received over time.

The state of the subscriber’s collection is described by an identifier. Packages received from the syndicator contain two identifiers called sequence identifiers. The first identifier describes the subscriber’s collection state before applying the package (the so-called old state). The second identifier describes the subscriber's collection state after applying the package (the so-called new state).

Table 1 shows an example of the package sequence identifiers for the scenario illustrated in figure 2.

The subscriber can apply a package only if the state of its collection matches the old state sequence identifier of the package. The subscriber reaches the new state as defined in the package if all instructions specified in the package have been carried out. If one of these instructions fails, all instructions specified in the package that have already been carried out are reversed. ICE has defined the following two special package sequence identifiers:

• ICE-INITIAL: The null state of the subscriber before any ICE operations have occurred
• ICE-ANY: Old state of a package, which may be applied regardless of the state of the subscriber’s collection

Table 2 shows a sequenced package example based on the scenario in figure 2.

Table 3 describes a strict implementation of the package sequence model; however, most real life implementations, including the ICE implementation of IBM Workplace Web Content Management, follow a less strict implementation (see table 3).

A less strict implementation facilitates the ICE-ANY package sequence described above. A package with the old state ICE-ANY updates the subscriber’s entire collection to the newest state, regardless of the subscriber’s current state.

Package containment model

Packages contain content as a set of instructions or operations for the subscriber. These remove and add operations use the addressing mechanism of a subscription element to reference and manage delivered content.

As explained earlier, each package moves the subscriber’s collection from an old state into a new state. You specify the remove operation by using the <ice-item-remove> element. The actual result is leading; if there is no item to be removed, the operation is still successful.

The add operation contains the content that needs to be added or updated, and you specify it using the <ice-item> and <ice-item-ref> XML elements. The <ice-item> element is used to contain content directly in the delivered package. The <ice-item-ref> element is used to distribute an indirect reference to the actual content. The result is also leading here; operations are still successful if content is added more than once.

NOTE: A package must contain at least one operation, and removals should be handled before any additions.

All operations specified in the package should be executed before the new state stated in the package can be reached. If an operation cannot be performed successfully, all previously performed operations specified in the package are undone, and an error code is sent to the syndicator.

Back to top

Implementing syndication in Workplace Web Content Management

The implementation of ICE in Workplace Web Content Management has not changed significantly in recent versions. This section explains the implementation of ICE and the interaction with Workplace Web Content Management’s data model.

Syndicator

The syndicator is defined in a syndicator item. In IBM Workplace Content Management V6, you can define a syndicator in the Portal Administration section as shown in figure 3. In earlier versions, you define it in the Web Content Authoring portlet.

The required fields of a syndicator item are specified in table 4.

In versions of Workplace Web Content Management prior to V6, a syndicator spans the entire datastore. In version 6, it is possible to partition a datastore into multiple (virtual) libraries. You can configure a syndicator to syndicate single or multiple libraries.

An item gatherer can be configured for each library. Item gatherers register all items that change in a library. The modification date of a document is used to determine these changes. An element (menu, navigator, and so on) or item (Content item, sitearea, site, and so on) is an atomic object; therefore, the item gatherer does not track any changes on the component (field) level of items or elements.

The item gatherer can be configured to gather all modified items in the library or to gather only modifications to published and live items.

The All Items Gatherer is appropriate when syndicating two servers that need to contain identical items, including draft items. The All Live Items Gatherer is appropriate when syndicating to, say, a delivery server. Only items that are crucial to the live site are gathered and syndicated, reducing the amount of data syndicated to the servers, and thus causing less impact on server performance.

At a specified time interval (by default, 30 seconds), a task checks the item gatherer to determine whether or not there have been any changes. If there have been changes, the syndicator assumes that the Workplace Web Content Management instance is busy, and it does not send an <ice-request> to the subscriber. If, however, the item gatherer has not registered any changes, the syndicator assumes that its instance is not busy and that syndication may occur. The syndicator then sends an <ice-request> to the subscriber to initiate syndication.

The earlier described task that detects whether or not the item gatherer has registered any changes runs every 30 seconds by default. You can configure this interval as shown in table 5.

The interval should be specified in seconds with a value between zero and 65536. A value of zero prevents syndication.

A long interval causes less syndication, but having the interval be too long may result in no syndication. For instance, if the interval is set to 12 hours, syndication will start when no changes occur during 12 hours. If a change occurs during these 12 hours, syndication must wait for another 12 hours. In many situations, it may be unlikely that no changes occur during such long intervals, so syndication does not occur at all.

The recommended value for the syndication interval on production servers is between 30 seconds and 10 minutes. For other servers, an interval between 10 minutes and two hours is advised.

Subscriber

The subscriber is defined in a subscriber item. In Workplace Content Management V6, you can define a subscriber in the Portal Administration section as shown in figure 4. In earlier versions, you can define it in the Web Content Authoring portlet.

The required fields of a subscriber item are specified in table 6.

The subscriber creates the libraries specified by the syndicator on the subscriber. It is not possible to syndicate content to an already existing library on the subscriber. Access rights on the library are also not syndicated; after the initial syndication, you must configure the security on the syndicated libraries. The access rights on the items and elements are syndicated.

Workplace Web Content Management uses <ice-item-ref> to externalize the actual retrieval of the items. The subscriber retrieves the items and puts them on a queue.

The subscriber checks the modification dates of the items in the queue. If the modification date is later than the current version of the item on the subscriber, the change is applied; if not, the change is not applied. This has no impact on the state of the subscriber; as stated earlier, the actual result is leading. If the subscriber’s version of the item is newer and the item specified in the package is not applied, the state of the subscriber still becomes the new state specified in the package.

Disassociation

In Workplace Web Content Management, there are multiple ways to structure your content hierarchically, including site frameworks (site, siteareas) and taxonomies (categories).

In pre-V6 releases of the product, the relationship between a parent node and a child node in these kinds of structures is stored in the parent node. When you add, for example, a new item in a sitearea, a pointer to your new item is set in the sitearea item. This means that a parent node is also being modified when you add or delete a child. The item gatherer registers this change and sends the parent and child to the subscriber during the next syndication.

As stated above, an item or an element is an atomic part, so during syndication the entire parent item -- including the pointers to the children -- is replaced. Children that were added to the parent on the subscriber are not referenced in the new parent item. These children are not known on the syndicator; therefore, the syndicated parent item does not have any pointers to these children. These children, which can be (content) items, siteareas, or categories, lose their position in the hierarchy. This is called disassociation.

In Workplace Web Content Management V6, the relationship between the parent and the children is stored in the parent and in the child. If the parent item is replaced during syndication, the child still has a reference to the parent and will not be disassociated. The order of the (content) items in a sitearea is stored in the sitearea item, so syndication may affect the order of the content items in the sitearea.

Back to top

Configuring a subscription

A best practice for configuring a subscription is to open two browser windows and to copy/paste the values from one window to another, following these guidelines:

• Create a new syndicator item (on the syndicator) and a subscriber item (on the subscriber). Copy the subscriber name, ID, and URL in the syndicator item and copy the syndicator name, ID, and URL in the subscriber item.
• Save the syndicator first, followed by the subscriber. It is important to do this because the subscriber checks the subscription on the syndicator.

NOTE: You cannot create a subscription for an existing library on the subscriber.

Manual actions

In Workplace Web Content Management, you cannot schedule syndication. You can, however, start the syndication process manually. This can be done on both the syndicator and subscriber in two ways:

• Update: This overrides the syndication interval and initiates syndication directly. The update follows the normal package sequence identifiers.
• Rebuild: This overrides the syndication interval and uses the ICE-ANY package sequence identifier to let the syndicator send all updates to the subscriber.

Prior to version 6 of Workplace Web Content Management, the manual actions must be started from the syndicator or subscriber item; in V6, these actions can be started from the views (see figure 5).

Generally, the rebuild functionality is used when the datastore on the subscriber is lost or corrupted.

You can disable automatic syndication in Workplace Web Content Management V6 by setting the variable in table 7 to false.

User repositories

In versions 2.5 and 5.1, Workplace Web Content Management used LDAP and IBM WebSphere Member Manager as user repositories. Workplace Web Content Management references the WebSphere Member Manager External ID and the full distinguished name (DN) in the security settings of each item and element in the datastore.

As long as the syndicator and subscriber are using the same LDAP server, there are no problems. The WebSphere Member Manager External ID and the full DN are known in both systems; however, there is a problem when, for example, the subscriber uses a different LDAP server. The references from the Workplace Web Content Management items are not valid because the WebSphere Member Manager External ID and probably the full DN are invalid.

For continuous automatic syndication between, say, an authoring Workplace Web Content Management instance and two delivery Workplace Web Content Management instances in an IBM WebSphere Portal cluster, all Workplace Web Content Management instances must use the same LDAP server. For manual syndication between a test and a production environment, for example, the workaround is to use the memberfixer tool.

Memberfixer can fix the references to the WebSphere Member Manager External ID and the full DN based on the user's identification number (UID) of the user(s) and user group(s). Memberfixer requires that the common name (CN) of the accounts are identical on the syndicator and subscriber. Table 8 shows the memberfixer commands in Workplace Web Content Management V6.

Always run the report task before any other memberfixer task. The commands listed can be combined in a single URL. For pre-V6 versions of Workplace Web Content Management, you can omit the library variable. (NOTE: This varies with the release of Workplace Web Content Management. Consult the appropriate Information Center for your release for the available commands).

HTTP server configuration

The items and elements retrieved by the subscriber could potentially be quite large. In some cases, this may generate issues while posting through an HTTP server, such as IBM HTTP server or Apache. It is, therefore, recommended to use the application server port of the IBM WebSphere Application Server (generally, port 9081 in WebSphere Portal installations) or another dedicated port for syndication.

Subscriber-only

A syndicator server uses multiple processes to gather and queue content for syndication, but these processes affect server performance. A subscriber-only server does not require these processes, so you can improve performance on the subscriber-only server by disabling the processes (see table 9).

The status of the syndicator and subscriber
The actual status of a subscription can be checked on either the syndicator or the subscriber. The status shows the current state of the actual process (see table 10).

The status can be seen in the Web Content Syndicators or Web Content Subscribers view in Workplace Web Content Management V6. In earlier versions, the status is shown in the actual subscriber or syndicator item (see figure 6).

The Last Update column shows when the last syndication occurred. In V6, this field is shown in the views; in earlier releases, this field is shown in the actual item. In V6, the last update entry provides a link to more details on that syndication session; the latter is in earlier versions of IBM Workplace Web Content Management shown in the item.

Details on syndication

The detailed view in Workplace Web Content Management V6 on the syndication session displays the details on the subscriber and syndicator (Name, ID, and URL). Besides those details, the view also contains the fields listed in table 11.

The partners in the subscription are in sync if the new state of the subscriber matches the new state of the syndicator. If syndication fails (can be checked in the Result field), the two state fields indicate the values that they should have been, not the actual value. Prior to IBM Workplace Web Content Management V6, the same fields were visible in the actual syndicator or subscriber items in the last update info section of the item.

Back to top

Final tips and hints

Configuring a subscription is quite straightforward, but keep in mind the following points:

• Do not use IP-addresses; use a dedicated port instead.
• Do not use different hostnames than those configured in the system when you configure syndicator and subscriber items. In earlier Workplace Web Content Management versions, this may cause syndication to fail.
• Use the subscriber-only configuration for delivery servers.
• Do not set the syndication interval to more than two hours, or syndication may not occur.
• IBM WebSphere Application Server dynacache may interfere with syndication. Specifically, dynacache may return improper responses that are not expected and may result in erroneous or incorrect output by the system. For more details, refer to technote #1242955: "Syndication does not work if WebSphere Application Server dynacache enabled."
• Syndicator and subscriber should always be the same version. Also, check fixpacks and interim fixes.
• Both subscription partners should share the same user repository if they use automatic syndication. If this is not the case, disable automatic syndication and perform manual syndication. The latter should be followed by executing memberfixer.

Also, note the following regarding syndication of libraries in IBM Workplace Web Content Management V6:

• You cannot set up a subscription for a library that already exists on the subscriber. The subscriber generates an error if it finds a library with the same name as the one specified in the subscription.
• Authorizations on libraries are not syndicated to the subscriber. They must be set manually. Authorizations on the items and elements are syndicated to the subscriber.
• Use libraries efficiently. For example, split your site into a content library and a design library. This makes it possible to syndicate the design from content separately, enabling you to realize selective syndication.
• Disassociation is a problem that can occur in all pre-V6 Workplace Web Content Management versions. Generally, it occurs when a single content hierarchy (being a site or taxonomy) is edited on multiple Workplace Web Content Management instances.
• Edit a site or taxonomy on only one Workplace Web Content Management instance.
• During the development process, use separate sites or taxonomies for the content in, say, a development and/or test environment. Restrict access to these sites and/or taxonomies to the respective development and test audiences.
• Limit direct references between design elements and content items. Use search rules instead. (This is a general best practice for all Workplace Web Content Management versions).

Resources

Learn

• IDEAlliance Inc. ICE specification Web site
  
  
• World Wide Web Consortium's NOTE-ice-19981026 page
  
  
• IBM WebSphere Portal Version 6.0 Information Center
  
  
• IBM Technote #1242955, "Syndication does not work if WebSphere Application Server dynacache enabled"
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Payloads
• Packages
• Implementing syndication in Workplace Web Content Management
• Configuring a subscription
• Final tips and hints
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Lotus on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers