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 Appendix C, "Troubleshooting."
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 Section 1.5, "Content Server Behavior."
WebCenter Content can also be deployed to an IBM WebSphere Application Server. For more information, see "Managing Oracle WebCenter Content on IBM WebSphere" in the Oracle Fusion Middleware Third-Party Application Server Guide.
When you create custom components or dynamic server pages, you work primarily with WebCenter Content files in these directories:
bin
config
components
resources
weblayout
Caution:
Modifying the default variables in these files can cause WebCenter Content to malfunction. For more information about configuration variables, see the Oracle Fusion Middleware Configuration Reference for Oracle WebCenter Content.
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 Oracle WebCenter Content Server, Oracle WebCenter Content: Inbound Refinery, or Oracle WebCenter Content: Records. This is essentially a read-only directory. The default location is WCC_ORACLE_HOME
/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 files include startup files (intradoc.cfg
and executables).
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 |
---|---|
Executables |
|
|
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 is 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. Example 1-1 shows a typical intradoc.cfg
file.
<?cfg jcharset="Cp1252"?> #Content Server Directory Variables IntradocDir=C:/oracle/idcm1/ WebBrowserPath=C:/Program Files/Internet Explorer/iexplore.exe CLASSPATH=$COMPUTEDCLASSPATH;$SHAREDDIR/classes/jtds.jar #Additional Variables HTMLEditorPath=C:/Program Files/Windows XP/Accessories/wordpad.exe JAVA_SERVICE_EXTRA_OPTIONS=-Xrs
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 |
---|---|
|
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 Admin Server General Configuration page. Example 1-2 shows a typical config.cfg
file.
<?cfg jcharset="Cp1252"?> #Content Server System Properties IDC_Name=idcm1 SystemLocale=English-US InstanceMenuLabel=JeanWTestSystem InstanceDescription=idcm1 SocketHostAddressSecurityFilter=127.0.0.1|10.10.1.14 #Database Variables IsJdbc=true JdbcDriver=com.internetcds.jdbc.tds.Driver JdbcConnectionString=jdbc:freetds:sqlserver://jwilsonnote:1433/oracle1;charset=UTF8;TDS=7.0 JdbcUser=sa JdbcPassword=UADle/+jRz7Fi8D/VzTDaGUCwUaQgQjKOQQEtI0PAqA= JdbcPasswordEncoding=Intradoc DatabasePreserveCase=0 #Internet Variables HttpServerAddress=jwilsonnote MailServer=mail.example.com SysAdminAddress=sysadmin@example.com SmtpPort=25 HttpRelativeWebRoot=/oracle/ CgiFileName=idcplg UseSSL=No WebProxyAdminServer=true NtlmSecurityEnabled=No UseNtlm=Yes #General Option Variables EnableDocumentHighlight=true EnterpriseSearchAsDefault=0 IsDynamicConverterEnabled=0 IsJspServerEnabled=0 JspEnabledGroups= #IdcRefinery Variables #Additional Variables WebServer=iis UseAccounts=true IdcAdminServerPort=4440 SearchIndexerEngineName=DATABASE VIPApproval:isRepromptLogin=true Vdk4AppSignature=SF37-432B-222T-EE65-DKST Vdk4AppName=INTRANET INTEGRATION GROUP IntradocServerPort=4444
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 data/components/ Directory
File | Description |
---|---|
Identifies components that have been added to the Content Server system and whether they are enabled or disabled. Example: |
|
|
Identifies the configuration status for a component. |
Example 1-3 shows a component
.hda
file that defines the configuration status for a component called help
.
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 |
---|---|
Holds base configuration files for Content Server. |
|
Holds Idoc Script |
|
Holds files that are used by the installer and related applications. |
|
Holds files that are processed by the publishing engine and end up in the |
|
Holds |
|
Holds localized string definitions for Content Server. |
|
Holds templates for Content Server reports. |
|
Holds resource definitions (queries, page resources, services, and other resource data) for Content Server. |
|
Holds Idoc Script resource table definitions. |
|
Holds templates for all Content Server pages (except reports). |
Table 1-5 describes the subdirectories of the resources/admin/
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.
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 describes. The first five types listed in the table are also called resource-type resources. Table 1-7 describes these resource 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, JSP, and clusters to more fully integrate Content Server into your site's current environment.
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 may 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.
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 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.
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.
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.
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:
Most product customizing can be done with a normal text editor, such as Microsoft WordPad or vi.
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.
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.
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.
Before you customize WebCenter Content, you need to understand the behavior of Oracle WebCenter Content Server:
Startup behavior
Resource caching
Page assembly
Database interaction
Localized string resolution
Application integrations
For an overview of Content Server administration, see "Overview of System Administration Tasks" in Oracle Fusion Middleware Administering Oracle WebCenter Content.
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. Section 1.5.1.1, "Startup Steps," describes each step in more detail.
Figure 1-1 Content Server Startup Behavior
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.
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 Admin Server General Configuration page, accessible from the Administration menu
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.
Content Server loads all of the components listed in IntradocDir
/data/components/idc
short_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
.
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.
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 idc
short-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 Chapter 11, "Getting Started with Content Server Components."
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:
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.
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 Section 7, "Changing System Settings."
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.
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 Section 24, "Getting Started with Integrating WebCenter Content into Your Environment."