Introduction to Developing with Oracle WebCenter Content

1 Introduction to Developing with Oracle WebCenter Content

This chapter provides an overview of Oracle WebCenter Content and describes skills, tools, and resources for customizing Oracle WebCenter Content Server.

This chapter includes the following sections:

For information about troubleshooting aids, see Troubleshooting.

1.1 Overview of WebCenter Content Architecture

Before beginning a customization project, you need to understand the architecture of WebCenter Content and how it works. To create a customization efficiently and effectively, you should have an understanding of the WebCenter Content directories and files, available resources, and Content Server behavior.

Content Server, the web user interface for WebCenter Content, is deployed as an application to an Oracle WebLogic Server domain. For information about how Content Server works, see Content Server Behavior.

1.1.1 WebCenter Content Directories and Files

When you create custom components or dynamic server pages, you work primarily with WebCenter Content files in these directories:

bin/
config/
components/
custom/
resources/
weblayout/

Caution:

Modifying the default variables in these files can cause WebCenter Content to malfunction. For more information about configuration variables, see the Configuration Variables in Oracle Fusion Middleware Configuration Reference for Oracle WebCenter Content

1.1.1.1 Terminology for WebCenter Content Directories

Oracle WebCenter Content documentation uses the following terms when referring to variables in the directories associated with the Oracle WebCenter Content installation, configuration, and deployment:

IdcHomeDir: This variable refers to the ucm/idc/ directory in the WebCenter Content Oracle home, where the Content Server media is located. The server media can run Content Server, Oracle WebCenter Content: Inbound Refinery, or Oracle WebCenter Content: Records. This is essentially a read-only directory. The default location is ORACLE_HOME/wccontent/ucm/idc/. The variable portion of the default location can be changed, but the path cannot be changed from ucm/idc/.
DomainHome: The user-specified directory where an Oracle WebCenter Content application is deployed to run on an application server. The DomainHome/ucm/short-product-id/bin/ directory contains the intradoc.cfg file and executables. The default location for DomainHome is MW_HOME/user_projects/domains/base_domain/, but you can change the path and domain name (base_domain) during the deployment of an Oracle WebCenter Content application to an application server.
short-product-id: An abbreviated name for the type of Oracle WebCenter Content application deployed to an application server. This name is used as the context root (default HttpRelativeWebRoot configuration value). Possible values follow:
- cs (Content Server)
- ibr (Inbound Refinery)
- urm (Records)
IntradocDir: The root directory for configuration and data files specific to a Content Server instance that is part of an Oracle WebCenter Content application deployed to an application server. This Idoc Script variable is configured for one type of Content Server instance: Content Server (cs), Inbound Refinery (ibr), or Records (urm). The default location of IntradocDir is DomainHome/ucm/short-product-id/, but the IntradocDir directory can be located elsewhere (as defined in the intradoc.cfg file). The specified directory must be an absolute path to the instance directory and must be unique to a particular server or node. The directory includes a bin/ directory, which contains the startup files (intradoc.cfg and executables).

1.1.1.2 The bin Directory

The bin/ directory is the root directory for Content Server startup files. It contains the intradoc.cfg file and the executable files that run Content Server services, applets, and utilities. It is located at DomainHome/ucm/short-product-id/bin/, in which short-product-id specifies whether it is for Content Server (cs), Inbound Refinery (ibr), or Records (urm). Table 1-1 describes the contents of the bin/ directory.

Table 1-1 Contents of the bin Directory for Startup Files

Element Description

Element	Description
Executables	Services `IdcServer` `IdcServerNT` Applet `IntradocApp` (launches all Admin tools) Utilities `BatchLoader` `Installer` `IdcAnalyze` `ComponentWizard` `SystemProperties` `IdcCommand`
`intradoc.cfg` file	Configuration file that contains the settings for Content Server services, applets, and utilities

Executables

Services

IdcServer
IdcServerNT

Applet

IntradocApp (launches all Admin tools)

Utilities

BatchLoader
Installer
IdcAnalyze
ComponentWizard
SystemProperties
IdcCommand

intradoc.cfg file

Configuration file that contains the settings for Content Server services, applets, and utilities

Note:

If Content Server is set up as an automatic service and you attempt to start a Content Server service (IdcServer or IdcServerNT) from the command line, you will receive an error message: The port could not be listened to and is already in use.

The intradoc.cfg file is used to define system variables for Content Server, including directory, Internet, and Inbound Refinery settings. Several of these variables can be set using the WebCenter Content System Properties utility. The following example shows a typical intradoc.cfg file.

intradoc.cfg File
<?cfg jcharset="Cp1252"?>
#Server System Properties
IDC_Id=UCM_server1

#Server Directory Variables
IdcHomeDir=ORACLE_HOME/wccontent/ucm/idc/
FmwDomainConfigDir=ORACLE_HOME/user_projects/domains/base_domain/config/fmwconfig/
AppServerJavaHome=JRE_HOME
AppServerJavaUse64Bit=true
IntradocDir=ORACLE_HOME/user_projects/domains/base_domain/ucm/cs/
VaultDir=ORACLE_HOME/user_projects/domains/base_domain/ucm/cs/vault/
WeblayourDir=ORACLE_HOME/user_projects/domains/base_domain/ucm/cs/weblayout/

#Server Classpath variables

#Additional Variables
UserProfilesDir=ORACLE_HOME/user_projects/domains/base_domain/ucm/cs/data/users/profiles/

1.1.1.3 The config Directory

The config/ directory is located at IntradocDir/config/. The default location of IntradocDir is DomainHome/ucm/short-product-id/, but the IntradocDir/ directory can be located elsewhere (as defined in the intradoc.cfg file). Table 1-2 describes the contents of the config/ directory.

Table 1-2 Contents of the config Directory

File	Description
`config.cfg`	Defines system configuration variables.

The config.cfg file is used to define global variables for the Content Server system. Several of these variables can be set using the WebCenter Content System Properties utility or by modifying the variables on the General Configuration page, accessible through the Administration, Admin Server, General Configuration menu option. The following example shows a typical config.cfg file.

Example - config.cfg File
<?cfg jcharset="Cp1252"?>
#Server System Properties
IDC_Name=InstanceName
IdcProductName=idccs
InstanceMenuLabel=InstanceName
InstanceDescription=Instance InstanceName
SocketHostAddressSecurityFilter=127.0.0.1|0:0:0:0:0:0:0:1

#Database Variables
SystemDatabase:DataSource=CSDS
SystemDatabase:UseDataSource=true

#Internet Variables
HttpServerAddress=host:16200
MailServer=mail
SysAdminAddress=sysadmin@example.com
HttpRelativeWebRoot=/cs/
UseSSL=No

#General Option Variables
IsAutoNumber=Yes
AutoNumberPrefix=ContentIDPrefix

#Additional Variables
UseAccounts=true
registerStartMenuActions=1
WebServer=javaAppServer
FileEncoding=UTF8

1.1.1.4 The components Directory

The IntradocDir/data/components/ directory contains the files that Content Server uses to configure system components. Table 1-3 describes the contents of the components/ directory.

Table 1-3 Contents of the components Directory

File	Description
`idcshort-product-id_components.hda`	Identifies components that have been added to the Content Server system and whether they are enabled or disabled. Example: `idccs_components.hda`.
`idcshort-product-id_components.hda`	Identifies the configuration status for a component.

The following example shows a component.hda file that defines the configuration status for a component called help.

Example - component.hda File
<?hda version="11.1.1.2.0-dev idcprod1 (091209T125156)" jcharset=UTF8 encoding=utf-8?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
@end
@ResultSet Components
2
name
location
help
components/help/help.hda
@end

1.1.1.5 The custom Directory

The custom components are developed by customers to enhance WCC functionalities.

1.1.1.6 The resources Directory

The IdcHomeDir/resources/ directory contains two directories: admin/ and core/.

The resources/core/ directory contains files that Content Server uses to assemble web pages. Table 1-4 describes the subdirectories of the resources/core/ directory.

Table 1-4 Contents of the resources/core Directory

Subdirectory	Description
`config/`	Holds base configuration files for Content Server.
`idoc/`	Holds Idoc Script `dynamichtml` and `dynamicdata` definitions.
`install/`	Holds files that are used by the installer and related applications.
`javascript/`	Holds files that are processed by the publishing engine and end up in the `weblayout` directory as raw JavaScript files.
`lang/`	Holds localized string definitions for Content Server.
`reports/`	Holds templates for Content Server reports.
`tables/`	Holds Idoc Script resource table definitions (queries, services, and other table resource data).
`templates/`	Holds templates for all Content Server pages (except reports).

Table 1-5 describes the subdirectories of the resources/admin/ directory.

Table 1-5 Contents of the resources/admin Directory

Subdirectory	Description
`idoc/`	Holds Idoc Script `dynamichtml` and `dynamicdata` definitions.
`tables/`	Holds Idoc Script resource table definitions.
`templates/`	Holds templates for all Content Server pages (except reports).

1.1.1.7 The weblayout Directory

The DomainHome/ucm/short-product-id/weblayout/ directory contains the files that are available to the web server for display on the various pages of the Content Server website. Table 1-6 describes the subdirectories of the weblayout/ directory.

Table 1-6 Contents of the weblayout Directory

Subdirectory	Description
`groups/`	Holds the web-viewable content items and dynamic server pages.
`images/`	Holds images, such as icons and home page graphics.
`resources/`	Holds layouts, skins, and schema information.

1.1.2 Resources

Resources are files that define and implement the actual customization you make to Content Server. They can be pieces of HTML code, dynamic page elements, queries that gather data from the database, services that perform Content Server actions, or special code to conditionally format information.

Resources are a critical part of the Content Server software, so you must be familiar with them before you attempt to create a custom component or dynamic server page. You can create, edit, or remove a resource file by using the Component Wizard. You also can use the Component Wizard as a starting point for creating custom resources.

Resources fall into eight distinct categories, which Table 1-7 describes. The first five types listed in the table are also called resource-type resources.

Table 1-7 Resource Types

Resource Type	Description	Example of Standard Resource
HTML Include	Defines pieces of HTML markup and Idoc Script code that are used on multiple Content Server web pages.	`IdcHomeDir/resources/core/idoc/std_page.idoc`
Dynamic Data Table	Defines a table of data in a `dynamicdata` include from within Idoc Script to load an HTML table definition, interface menu actions, or information about metadata fields or from within Java code as an alternative to static tables loaded into SharedObjects.	`IdcHomeDir/resources/core/idoc/std_data.idoc`
String	Defines localized strings for the user interface and error messages.	`IdcHomeDir/resources/core/lang/cs_strings.htm`
Dynamic Table (HDA format)	Provides dynamic (frequently changed) content in table format to Content Server.	`IdcHomeDir/resources/core/templates/templates.hda`
Static Table (HTML format)	Provides static (seldom changed) content in table format to Content Server.	`IdcHomeDir/resources/core/tables/std_locale.htm`
Query	Defines database queries.	`IdcHomeDir/resources/core/tables/query.htm`
Service	Defines scripts for services that can be performed by Content Server.	`IdcHomeDir/resources/core/tables/std_services.htm`
Template	Defines templates, which contain the code that Content Server uses to assemble a particular web page.	`IdcHomeDir/resources/core/templates/checkin_new.htm`
Environment	Defines configuration settings for Content Server.	`IntradocDir/config/config.cfg`

1.2 Customization Types

Three major types of alterations can be made to Content Server:

Altering the look and feel of the product

You can customize the look and feel of the Content Server interface to meet your organization's specifications. Interface modifications can be as simple as replacing the icons that appear on the standard Content Server web pages or as complex as a complete redesign of the interface.
Modifying the functionality of the product

By changing how the product functions, you can tailor Content Server to the way your business or organization functions. For example, you can change the default date and time stamp, or change aspects of check-in behavior.
Integrating the product into your environment

You can use shell scripts, SOAP, J2EE, and clusters to more fully integrate Content Server into your site's current environment.

1.3 Customization Planning

Before approaching customization, it is important to clarify exactly why the customization is being undertaken. For example, to add corporate branding, you can use the Modify Layout Samples to do so. Or to change security features, you can use components to modify the default security settings.

Customization often occurs to make Content Server match the business practices of an organization. Often, after evaluating your business processes, you may find that sometimes it is more efficient to slightly alter your procedures before customizing Content Server.

There are six major stages in customization:

Determine why you want to customize.

Is there corporate personalization to be done? Is there a better way to present navigation options or material? Depending on what type of need you find, you can determine which tools are best to use.

Oftentimes the cosmetic details that you change are the ones that can most satisfy your users; changing items such as layout, colors, and images often provide the effect that users are looking for.
Plan the customization carefully.

Take into account those aspects of the Content Server environment that might be changed even peripherally by the customization. All customization should be done in a test environment, separate from the site's production environment.
Check to see if a solution might be available.

The samples on the Support website contain many types of customizations. You might be able to use an existing component with just a little editing. A number of samples are provided on an as-is basis. These are components or files that demonstrate, enhance, or extend the functionality of WebCenter Content.
Evaluate the problem and how essential it is to solve.

Some problems might require more effort to fix than the resulting payback. Perhaps customization is not needed, but simply a minor change in business practices.
Test the customization thoroughly in a separate environment.

If possible, have end users assist with the testing. When the testing has passed all criteria for release, inform users about the changes and how to implement them.
Document the customization that you create.

All alterations should be documented as completely as possible, both within the actual customization (for example, as a comment in a dynamic server page or in a component) and as a separate README document. This documentation provides a historical audit trail for others who might need to add to the customization later.

1.4 Recommended Skills and Tools for Customizing Content Server

Content Server brings together a wide variety of technologies to deliver advanced functionality. To modify Content Server, certain experience and skills with some or all of these technologies are required.

The technical skills required to customize Content Server can vary depending on the complexity of the customization. For example, much customization can be accomplished with knowledge of HTML and Idoc Script.

This list describes, in descending order of importance, the technologies and experience you might need to modify Content Server:

Content Server architecture

You should thoroughly understand how Content Server works and how components and dynamic server pages function before you begin customizing your system.
HTML and cascading style sheets (CSS)

You will need a good understanding of HTML and CSS to make changes to the Content Server web page templates. The templates are not complex in their use of HTML, but they make constant use of HTML tables and frequent use of forms. The std_page.idoc and std_css.idoc files include cascading style sheets to control the look and feel of the default templates, including fonts and layouts.
Idoc Script

Idoc Script is the custom, server-side scripting language for Content Server. Almost every Content Server web page includes some Idoc Script code, which provides the methods for processing various page elements.
JavaScript

The internal content of most Content Server pages do not use JavaScript, but the Search, Check-In, and Update pages are notable exceptions. You must have an understanding of JavaScript before you create a customization that is called in place of these pages. Also, you must understand JavaScript to alter layouts. Changing layouts relies heavily on JavaScript and cascading style sheets for design and navigation.
Structured Query Language (SQL)

Content Server uses SQL to perform queries on the database. Knowledge of SQL can help you understand the standard queries and create your own custom queries.
Java programming

Content Server is implemented with Java classes. You should have a thorough understanding of Java and the Content Server Java class files before attempting to make any changes to the underlying functionality. However, you can customize the product extensively without working with Java.
Other programming

Experience with other tools, such as Visual Basic, COM, .Net, C++, or VBScript, might be helpful if you are doing complex customization or integrating WebCenter Content with other systems.

You may find the following tools useful when customizing Content Server:

Text editor

Most product customizing can be done with a normal text editor, such as Microsoft WordPad or vi.
HTML editor

Caution:

Graphical HTML editor programs often change the source HTML, which can cause Idoc Script tags to be converted into strings of characters that are no longer recognized by Content Server. If you use a graphical editor, make sure you edit in a nongraphical mode.

If you prefer to use a graphical HTML editor to work with HTML pages, use a nongraphical mode for editing.
Multiple browsers

You should test customization on multiple versions of any web browsers that might be used to interface with the content management system. Internet Explorer, Firefox, and Chrome do not display content in the same manner, and different versions of the same browser may exhibit different behaviors.
JavaScript debugger

A JavaScript debugger can ease the task of JavaScript development. A number of JavaScript debuggers are available for download from the Internet.
Integrated Development Environment (IDE) for Java

If your customization requires the development of Java code, you need an appropriate Java development environment.

1.5 Content Server Behavior

Before you customize WebCenter Content, you need to understand the behavior of Content Server:

For an overview of Content Server administration, see Introduction to Administering Oracle WebCenter Content in Oracle Fusion Middleware Administering Oracle WebCenter Content.

1.5.1 Startup Behavior

During startup, a Content Server instance performs internal initialization and loads these items:

Configuration variables
Standard templates, resources, and reports
Custom components, including templates, resources, configuration variables, and reports

Figure 1-1 illustrates the four steps that Content Server goes through during startup. Startup Steps, describes each step in more detail.

Figure 1-1 Content Server Startup Behavior

Description of "Figure 1-1 Content Server Startup Behavior"

1.5.1.1 Startup Steps

During startup, Content Server goes through these steps:

Internal initialization occurs.

When Content Server initializes internally, the Java class files from Content Server are read and the Java Virtual Machine (JVM) is invoked. Any variables in the DomainHome/ucm/short-product-id/intradoc.cfg file are initialized as well.
Configuration variables load.
After initialization, Content Server loads the config.cfg file from the IntradocDir/config/ directory. This file stores the system properties and configuration variables, which are defined by name/value pairs (such as SystemLocale=English-US).

The default information contained within the configuration file was supplied during the Oracle WebCenter Content installation process, but you can modify this file in several ways:
- Use the General Configuration page, accessible through the Administration, Admin Server, General Configuration menu option
- Run the SystemProperties executable, located in the bin/ directory of the Oracle WebCenter Content installation (UNIX operating system)
- Edit the configuration files directly
- Use a custom component
Any time changes are made to the config.cfg file, you must restart Content Server for the changes to take effect.
Standard resources, templates, and reports load.

For Content Server to function properly, many standard resources, templates, and reports must be loaded. After the configuration settings have been loaded, Content Server reads the entries in the IdcHomeDir/resources/core/templates/templates.hda file and the IdcHomeDir/resources/core/reports/reports.hda file. These files tell Content Server which templates to load, which in turn loads any standard resources referenced in the template and report pages.
Custom components load.

Content Server loads all of the components listed in IntradocDir/data/components/idcshort_product_id_components.hda, and in turn that loads system components out of IdcHomeDir/components/ComponentName/ComponentName.hda or, for custom components, out of IntradocDir/custom/ComponentName/ComponentName.hda.

1.5.1.2 Effects of Configuration Loading

It is important to understand the effect of the load order for the different configuration files because if a variable is set in more than one file, the last variable loaded takes precedence. For example, the IntradocDir/config/config.cfg file is loaded before the IntradocDir/data/components/component_name/config.cfg file, so the component_name/config.cfg can change the value of a variable that was set by the config/config.cfg file.

Files are loaded in this order (not all files exist for each component):

DomainHome/ucm/short-product-id/bin/intradoc.cfg
IntradocDir/config/config.cfg
DomainHome/ucm/short-product-id/custom/component_name/*_environment.cfg

Some components might not have this file, or it might be named environment.cfg.
IntradocDir/data/components/component_name/install.cfg
IntradocDir/data/components/component_name/config.cfg
DomainHome/ucm/short-product-id/bin/intradoc.cfg

This file is reread at the end of startup to allow overrides to other settings.

If, for example, the same variable was set in each of the files in the list, the variable's value in intradoc.cfg would take precedence because this file was loaded last.

To view the configuration, you can use the GET_SYSTEM_AUDIT_INFO service to show all configuration entries and where they were set.

To change a component variable, you can use the Update Component Configuration area in the Advanced Component Manager. This area displays a dropdown list of components that have editable configurations in the component_name/config.cfg file. You can choose a component and click Update to get to the Update Component Configuration page in Content Server.

You can also edit the configuration file manually. If a component is not displayed in the Update Component Configuration list in the Advanced Component Manager, you can make your changes directly in one of the configuration files.

1.5.2 Resource Caching

Content Server handles caching for template pages and resources as follows:

When Content Server loads template pages and resources, they are cached in memory to accelerate page presentation.
If you change a template page, report page, or HTML include resource, or you check in a revision to a dynamic server page, your changes go into effect immediately.

The next request for the associated web page or refresh of the page reflects the changes, and the new information is cached. This occurs because pages are assembled dynamically for each page request. You can disable this behavior to improve performance by setting the configuration variable DisableSharedCacheChecking.
If you change any other component file (including services, queries, environment variables, tables, the idcshort-product-id_components.hda file, and the template.hda file), you must restart Content Server before the changes go into effect. Such changes could cause Content Server to malfunction if they were implemented immediately.

You do not need to restart Content Server after changing strings; however, you must republish the ww_strings.js files by clicking publish string and dynamic files or publish string, static, and dynamic files in the Weblayout Publishing area of the Admin Actions page. For more information, see Getting Started with Content Server Components.

1.5.3 Page Assembly

Content Server uses the following information from the files in the IdcHomeDir/resources/ directory to assemble dynamic web pages:

The structure and format of a web page

This structure and format are defined by a particular HTML template file. The template files are primarily in the resources/core/templates directory, and some templates are in the resources/core/reports and resources/admin/templates directories.
The templates reference resources

These resources are located in .htm and .idoc files in subdirectories of the resources directory. Resources can include HTML and Idoc Script markup, localized strings, queries to gather information from the database, and special code to conditionally format the information.

As a rule, each web page includes the following resources:

Standard page header
Standard page beginning
Standard page ending

Because all of the Content Server resources are cached in memory at startup, Content Server has a definition for the standard pieces that appear on the page. Content Server then combines the standard resources with the unique resources specified in the template to create the web page.

For dynamic server pages, the template page and custom resource files are checked into Content Server. When one of these pages is requested by a web browser, Content Server recognizes the file extension as a dynamic server page, which enables special processing. At that point, the page assembly process is the essentially the same as the standard process, except that the page can use both the standard resources in the resources directory and the custom resources that are checked in to Content Server.

1.5.4 Database Interaction

Some databases, such as Oracle Database, return all column names in uppercase characters. Therefore, when Content Server receives query results from these databases, column names must be mapped from the uppercase characters to the values used in Content Server.

Because of this case mapping issue, custom components created for a Content Server instance using one database might not work correctly on a Content Server instance using a different database.

To map column names, the IdcHomeDir/resources/core/resources/upper_clmns_map.htm file contains a mapping table named ColumnTranslation. Add the query values to this file when you create a component that accesses fields that are not WebCenter Content database fields (for example, if you create a component that accesses a custom table within the WebCenter Content database).

For information about using the upper_clmns_map.htm file, see Changing System Settings.

1.5.5 Localized String Resolution

Localized strings are the means by which the user interface and error messages are presented in the language specified by the user's locale. Content Server loads the string resource files for a base language and also loads resource files for every supported language. Instead of presenting hard-coded text, the template pages, applets, and error messages reference string IDs in these resource files, which are then resolved using the ExecutionContext that contains the locale information for the user.

1.5.6 Application Integrations

Content Server not only serves as a content management solution for content-centric websites, but also provides a scalable content management infrastructure that supports multiple enterprise applications in many diverse environments and platforms. The integration solutions enable other enterprise applications to access content managed by the content management system and provides these applications with critical content management capabilities such as full-text and metadata searching, library services, workflow, subscription notifications, and content conversion capabilities through a wide array of integration methods.

For information about integrating Content Server with enterprise applications, see Getting Started with Integrating WebCenter Content into Your Environment.