33 Understanding WebCenter Content Integration

To integrate WebCenter Content with WebCenter Sites, become familiar with the prerequisites of WCC integration. Also learn how you can configure WCC and manage synchronized content.

This chapter also describes enabling two WCC Integration parts: the SitesIntegration component and the Connector Admin tab.

The Oracle WebCenter Content Integration feature, also called WCC Integration, is a GUI-controlled connector. It synchronizes content items from WebCenter Content to WebCenter Sites, where they are managed as native assets. The assets can be edited, deleted, previewed, revision tracked, published, and otherwise treated like any asset that is created directly in WebCenter Sites.

Before you can start configuring your system for content synchronization, you must enable the SitesIntegration component and the Connector Admin tab. Each step is described in its own section.

The following topics provide information about WebCenter Content integration:

33.1 Prerequisites for Administering WCC Integration

WCC Integration is for administrators with a working knowledge of WebCenter Content and WebCenter Sites, especially their data models. You must have a clear understanding of content items, renditions, conversions, and metadata defined in WebCenter Content. You must also have a clear understanding of WebCenter Sites asset types, the flex family in particular. A critical portion of your work involves mapping content item metadata to asset type attributes. If you have to create the asset types, you must collaborate with developers.

For more information about WebCenter Content, see Getting Started with Oracle WebCenter Content in Using Oracle WebCenter Content.

33.2 Basics of WebCenter Content Integration

WCC Integration leverages WebCenter Content and the conversion capabilities of its content transformation engines. Specifically, WCC Integration is designed to synchronize two types of content from WebCenter Content to WebCenter Sites – documents and digital assets, including images and videos – as native files, renditions, and HTML conversions. You can create renditions with the core transformation engine or Digital Asset Manager, depending on the type of native file and which renditions are required. HTML conversions are generated by Dynamic Converter. File formats are unlimited. For more information about content transformation, see Viewing Alternate Renditions in Using Oracle WebCenter Content.

Before you enable and set up WCC Integration, review the concepts that are fundamental to WCC Integration. These concepts are used throughout the WCC Integration feature and the chapters in this guide. They include the WebCenter Content data model, its mapping to asset types in WebCenter Sites, and the rules you configure to guide the connector when it polls WebCenter Content. The concepts are discussed in WebCenter Content Data Model and Asset Type Mapping and Connector Rules.

33.3 WebCenter Content Data Model

The WebCenter Content data model is based on an object called content item, which holds several types of information: a native file, its renditions, conversions, and the associated metadata.

Native files are created by users directly in WebCenter Content and kept in their original format. For WCC Integration, valid native files are documents (such as docx files) and digital assets (such as image files and videos).
Renditions are converted content items. Renditions are different formats of native content. They are files generated by content transformation engines and associated with the content item that stores the native (original) file.

For example:
- You can convert native documents with the core transformation engine (available by default in WebCenter Content) into web formats for easier viewing on the web, such as converting a Microsoft Word document into a PDF file. The native document is known as the primary rendition, and its web-viewable copy is known as the web rendition. The native file and its rendition are contained within the same content item.
- Digital Asset Manager can convert native image files and videos into multiple renditions of different sizes and formats. The original image file is the primary rendition, its small thumbnail version could be called small thumbnail rendition, its large thumbnail version could be called large thumbnail rendition, and so on.
HTML conversions are specific renditions of native documents (such as Microsoft Word). The renditions are created by Dynamic Converter, which takes a single native document containing both text and graphics and converts it into an HTML rendition. The rendition consists of (1) an HTML file containing all the text of the native document, and (2) a collection of image files representing the graphics. To allow the Dynamic Converter and the Sites Integration components to operate correctly together, set the default character set in the JVM to UTF-8. This allows the Sites Integration component to correctly interpret the HTML generated by Dynamic Converter. Apply the JVM argument -Dfile.encoding=UTF-8 to the JVM that hosts the WebCenter Content.
Metadata associated with content items is analogous to attributes associated with asset types.

When it runs for the first time, the WCC connector imports the latest released versions of native files, renditions, conversions, metadata, or combinations of them into WebCenter Sites. Which content it imports depends on the connector rules and the mappings they specify.

If the content items are then modified on WebCenter Content, the connector synchronizes them to WebCenter Sites in its next session. Updated content items are re-imported into WebCenter Sites, and deleted content items have their counterpart assets deleted from WebCenter Sites (unless dependencies on those assets were created since the last synchronization session).

You can trigger import and synchronization manually, or you can schedule them to run on a timed basis.

Synchronization is always unidirectional, from WebCenter Content to WebCenter Sites. WCC Integration supports a many-to-one client/server model. You can connect any number of WebCenter Sites clients to a single WebCenter Content instance.

33.4 Asset Type Mapping and Connector Rules

In WebCenter Content, managed items are referred to as content items, while in WebCenter Sites the managed items are referred to as assets.

Content items in WebCenter Content have metadata associated with them.
Assets in WebCenter Sites are instances of asset types, which have attributes associated with them.

The goal of using WCC Integration is to import content items as assets into WebCenter Sites and keep them synchronized as the content items are updated. Your success depends on many factors, but rests largely on the target asset type (or types), especially on the mapping of content item metadata to asset type attributes, how you configure the mapping in rules the connector uses throughout its polling sessions, and how you prioritize the rules.

This section covers the following topics:

33.4.1 Asset Type Mapping

You can create and reuse target asset types. How many and which asset types to use depends on your content requirements. There is, however, a minimum set of requirements:

Target asset types must belong to the flex family.
A target asset type must have at least the following types of attributes:
- A content identifier attribute that maps to the content identifier metadata field used in WebCenter Content.
- Content storage attributes to hold the imported files (native files, renditions, conversions, or any combination of them).
- A template storage attribute to enable asset previewing, assuming asset previewing is a requirement (which is typically the case).
  
  If you create a template attribute, you must give special attention to template code for previewing dynamically converted HTML files and their referenced images.
The rest of the requirements are specific to your requirements.

33.4.1.1 Content Identifier Attribute

In WebCenter Content, each item has a unique ID, which is stored in a database field named dDocName (and displayed in the Content ID field). By default, dDocName is mapped to the name attribute. Whenever an asset is created in WebCenter Sites to store a content item, the value of dDocName for that content item is recorded in the name attribute.

The dDocName (Content ID) is used in several ways. It enables the WCC connector (and you) to trace assets to their counterpart content items. It enables the connector to determine if a content item has been synchronized to WebCenter Sites and, therefore, to either create an asset, update the existing asset, or delete the existing asset, depending on whether the content item is created, updated, or deleted.

The default mapping of dDocName to name can be changed. This is done only one time, on a new system, before connector rules are created and the first synchronization session is started.

33.4.1.2 Content Storage Attributes

Given that content items are imported into WebCenter Sites as files, the target asset type requires attributes of type blob (either single- or multi-valued) to accept the files.

Dynamically converted documents require some special handling, because the process of converting a single native file into HTML generates multiple artifacts. For example, a single Microsoft Word document containing both text and graphics gets converted to (1) an HTML file containing all the text, and (2) a collection of image files representing all the graphics.

The HTML and image files are mapped to separate attributes. The HTML file is mapped to a single-valued attribute of type blob. The image files are mapped to a multi-valued attribute of type blob. A template attribute and template for previewing the asset must also be configured.

33.4.1.3 Template Attributes

Typically, asset types in WebCenter Sites have template attributes to support asset previewing.

Templates Requiring Special Attention

Templates for dynamically converted HTML files require special attention for the following reason:

A dynamically converted HTML file contains image links in WebCenter Content format. For example:

<img src="${wcmUrl('dcresource','20673.jpg')}" 
width="360" height="270" alt="2007_06240117.JPG" />

Because WebCenter Sites does not recognize a format such as ${wcmUrl('dcresource','20673.jpg')}, you must convert the links to blob links. Conversion of link format is illustrated in a sample template named WccConversionPreview.jsp, located in the /misc/Samples/WCC directory of the exploded WebCenter Sites distribution file. Developers can use the sample template as is, or include parts of its logic in their own templates. The sample template is hard-coded with the names of the file-storage attributes shown in the following table:

Table 33-1 Attributes in WccConversionPreview.jsp

Attribute Name	Data Type
html	`blob`
images	`blob (M)`

If the attributes in your target asset type are named other than html and images, developers must update the sample WccConversionPreview.jsp template with the attribute names used in the target asset type.

33.4.1.4 Administrator-Defined Specifications

You always have the option to add attributes for any metadata that you must synchronize to a target asset type.

You can enable target asset types on as many content management sites as necessary. During a synchronization session, content items are synchronized to the target asset types on all sites that you specify in the connector rules.

33.4.2 Connector Rules

The WCC connector requires at least one active (enabled) rule. Without an active rule, the connector cannot poll WebCenter Content.

An active rule is an enabled set of instructions for the connector to execute when it runs. A rule is configured and enabled on WebCenter Sites. It contains several instructions: Which metadata to poll on WebCenter Content, which target asset type to use on which content management sites where the target asset type is enabled, and how to map content item metadata to asset type attributes. The connector uses the map to determine in which attributes to store the information it retrieves.

When planning and configuring connector rules, consider the information presented in the rest of this section to help ensure that content items are processed to your expectations:

Rules and Target Asset Types
Prioritizing Active Rules
Resynchronizing Content Items to WebCenter Sites
Disabling and Deleting Active Rules
Additional Considerations

Rules and Target Asset Types

A connector rule specifies a single target asset type only, which means that you are likely to create multiple rules if you plan to synchronize a variety of content items to WebCenter Sites. For example:

You want to import a dynamically converted HTML file and its referenced images into a single asset type. You then create a single rule that names the target asset type and maps the HTML file with its images to an html attribute and an images attribute.
You want to import Microsoft Word documents and unrelated pdf files. You have two dedicated asset types: one asset type for docx files, and the other asset type for pdf files. You then create two rules: one rule for synchronizing the docx files to the first asset type, and another rule for synchronizing pdf files to the second asset type.

Prioritizing Active Rules

If multiple active rules map the same content items to different asset types, only one rule is executed by the connector – the first rule that matches the content items. The order in which rules are executed determines which content items are synchronized to which asset types.

For example, you have new items named surfing.jpg, surfing.png, and skiing.png. You also have two active rules:

Rule 1 maps surfing.any_extension items to the Images_avi asset type on the avisports site.
Rule 2 maps png items to the Images_FSII asset type on FirstSite II.

Table 33-2 shows that the items are distributed differently between the two asset types when rule 1 and rule 2 are executed in different orders. Therefore, you must prioritize the rules in a way that produces the results you require.

Table 33-2 How the Order of Active Connector Rules Determines Content Distribution

Active Rule	Images_avi Target Asset Type	Images_FSII Asset Type
If rule 1 is executed first	`surfing.jpg` and `surfing.png` are imported into this asset type	`skiing.png` is imported into this asset type
If rule 2 is executed first	`surfing.jpg` is imported into this asset type	`surfing.png` and `skiing.png` are imported into this asset type

The connector uses rules to synchronize content items to WebCenter Sites as follows:

When the connector runs, it examines new and updated content items, but only if they are (or were) enabled for synchronization. The connector examines the content items one at a time, as follows:

The connector compares the metadata of a content item to the metadata in the rule. If the connector fails to find matching metadata, it uses the next active rule to re-test the same content item.

If it finds matching metadata, the connector continues to test the content item by looking for renditions that match renditions specified in the rule. After its search is complete, the connector turns to WebCenter Sites (regardless of whether it finds matching renditions).
On WebCenter Sites, the connector operates on the database:

The connector calls the target asset type named in the rule, creates an asset, uses the rule to determine which metadata maps to which attributes, and imports the metadata values and renditions (if any) into the attributes for the asset.

After the imported content item is synchronized, the connector skips testing all other rules on that content item and moves on to test the next content item, starting with step 1.

Resynchronizing Content Items to WebCenter Sites

After a content item is synchronized to WebCenter Sites, it is resynchronized only when it is modified (updated or deleted) on WebCenter Content.

Note:

If a content item is synchronized to WebCenter Sites and then deleted from WebCenter Content, its counterpart asset is deleted from WebCenter Sites, unless dependencies were created on that asset since the last synchronization session.

Disabling and Deleting Active Rules

If an active rule is disabled or deleted, content items imported into WebCenter Sites by that rule remain in WebCenter Sites. Disabled rules are ignored by the connector.

Additional Considerations

Creating and managing rules is only one part of setting up content synchronization. Your complete set of steps includes first enabling several WCC Integration parts (a one-time operation) and then configuring the parts to support content synchronization. The parts are described in WebCenter Content Integration and Its Parts.

33.5 WebCenter Content Integration and Its Parts

The WCC Integration feature consists of several parts, which you must first enable and then configure to set up and manage content synchronization. The parts are the SitesIntegration component, the WCC connector, and the Connector Admin tab, which is used to control the connector.

SitesIntegration: This component is installed by default on WebCenter Content during the installation process. You must enable it to support the WCC connector.

Enabling the SitesIntegration component adds the following features to WebCenter Content:
- Sync to Sites option. This option opens on content check-in, update, and search forms. Setting the option to True makes the content item available to the connector for retrieval. Whether the content is actually retrieved and stored depends on whether that content matches the criteria in the active rules you create.
- WCS Queue Support Information. This graphical interface lists token history for each of the WebCenter Sites clients. You can use token information to roll back to previous updates.
See Enabling the SitesIntegration Component.
WCC Connector: This connector is installed on WebCenter Sites to communicate with WebCenter Content. You can install it during the WebCenter Sites installation or upgrade process, or at a later time (the former method is preferred). The connector polls WebCenter Content after it is configured to do so from the Connector Admin tab in the WebCenter Sites Admin interface.
Connector Admin: This is a graphical interface used to control the connector. When WCC Integration is installed, the Connector Admin node is added to the navigation tree of the WebCenter Sites Admin interface, as shown in the following figure.

Figure 33-1 WCC Connector Admin Node

Description of "Figure 33-1 WCC Connector Admin Node"

Use the Connector Admin node to set up, run, and manage the connector. For example, you can create and enable connector rules, establish a connection to WebCenter Content, manually run the connector, monitor connector activity, view connector history, and obtain token information.

See Enabling Access to the Connector Admin Node.

33.6 Enabling the SitesIntegration Component

The SitesIntegration component is installed during the full Oracle WebCenter Content installation or upgrade process. After the SitesIntegration component is enabled, the following features are added to WebCenter Content:

The SiSyncToSites metadata field is added to WebCenter Content schema and displayed as the Sync To Sites option in content check-in, update, and search forms.
The WCS Queue Support Information page is added to provide a listing of WebCenter Sites clients and their token histories. After synchronization begins, the same page logs the synchronized content items and their update histories.

To enable the SitesIntegration component

On WebCenter Content, open the Component Manager page:
1. Click Administration on the portal navigation bar for your Content instance.
2. Click Admin Server.
On the Component Manager page:
1. Scroll down to the Integration section and select the SitesIntegration check box.
2. Click Update.
Note:

For more information about enabling components, see Configuring the WebCenter Content Domain in Installing and Configuring Oracle WebCenter Content .
Restart WebCenter Content.
Open any content check-in, update, or search form to verify that the Sync To Sites check box opens in the form, as shown in the following figure.

Figure 33-2 Sync To Sites Option on a Content Item Update Form

Description of "Figure 33-2 Sync To Sites Option on a Content Item Update Form"
Verify the display of the WCS Queue Support Information page:
1. Log in to WebCenter Content as an administrator.
2. Select Administration and then WCS Administration to open the WCS Queue Support Information page (in the following figure).
  
  Figure 33-3 WCS Queue Support Information Page on WebCenter Content Server
  
  Description of "Figure 33-3 WCS Queue Support Information Page on WebCenter Content Server "
Continue to Enabling Access to the Connector Admin Node.

33.7 Enabling Access to the Connector Admin Node

You must assign the ConnectorAdmin role to anyone who must use WCC Integration. The only exception is noted below.

Note:

The ConnectorAdmin role is automatically assigned to one user only, and that is the general administrator whose credentials were used during the WebCenter Sites installation process. All other users, including general administrators, must have the role assigned to them manually.

The ConnectorAdmin role grants access to the Connector Admin node, enabling its user (typically an administrator) to control the connector by performing such operations as creating and managing its rules, establishing communication with WebCenter Content, running the connector, monitoring its activity, and viewing its history.

To enable access to the Connector Admin node:

Open the Admin interface on the content management site you intend to work with, and look for the Connector Admin node (shown in the following figure).

Figure 33-4 Connector Admin Tab

Description of "Figure 33-4 Connector Admin Tab"
If the Connector Admin node is not displayed, assign yourself (and other intended users) the ConnectorAdmin role. See Working with ACLs and Roles.
Log out of the Admin interface, and log back in to the same content management site as in step 1 of this procedure.