1 Introduction to Customizing Your Oracle UCM Instance

This chapter provides an overview of Oracle Universal Content Management (Oracle UCM) customization and describes the tools you need and the resources that are available.

This chapter includes the following sections:

1.1 Customization Types

Three major types of alterations can be made to the core Oracle Content Server instance:

  • Altering the look and feel of the product: You can customize the look and feel of the Oracle Content Server interface to meet your organization's specifications. Interface modifications can be as simple as replacing the icons that appear on the standard Oracle 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 Oracle 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 Oracle Content Server into your site's current environment.

1.2 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 Oracle 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 Oracle Content Server.

There are six major stages in customization:

  1. 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.

  2. Plan the customization carefully, taking into account those aspects of the Oracle 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.

  3. Check to see if a solution may be available. The Samples on the Support web site contain many types of customization. It's possible that there may be an existing component that can be used 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 your Oracle UCM products.

  4. Evaluate the problem and how essential it is to solve. Some problems may require more effort to fix than will provide payback. Perhaps customization is not needed, but simply a minor change in business practices.

  5. 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.

  6. 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 provides an historical audit trail for others who may need to add to the customization later.

1.3 Recommended Skills and Tools

Oracle UCM brings together a wide variety of technologies to deliver advanced functionality. To modify the system, certain experience and skills with some or all of these technologies is required.

The technical skills required to customize your content management system 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 may need to modify Oracle Content Server:

  • Oracle Content Server Architecture

    You should thoroughly understand how Oracle Content Server works and how components and dynamic server pages function before you begin customizing your system.

  • HTML/CSS

    You will need a good understanding of HTML and cascading style sheets (CSS) to make changes to the Oracle 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 layout.

  • Idoc Script

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

  • JavaScript

    The internal content of most Oracle 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 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.

  • SQL

    Oracle Content Server uses Structured Query Language to perform queries on the database. Knowledge of SQL can help you understand the standard queries and create your own custom queries.

  • Java programming

    Oracle Content Server is implemented with Java classes. You should have a thorough understanding of Java and the Oracle 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++, VBScript, and so forth may be helpful if you are doing complex customization or integrating Oracle UCM with other systems.

You may find the following tools useful when customizing Oracle 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 may cause Idoc Script tags to be converted into a string of characters that are no longer recognized by Oracle 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, Netscape, Mozilla, and Safari 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.4 Troubleshooting

Several troubleshooting aids are available to help evaluate Oracle Content Server pages as they are used. The following sections discuss three broad types of troubleshooting aids:

1.4.1 Viewing Server Errors

Syntax errors and other mistakes in component files or dynamic server pages can cause errors in Oracle Content Server. If the Oracle Content Server instance fails, it reports the error in the following locations:

  • If you run Oracle Content Server from a command prompt, you can view the error in the console window.

  • If you can log in to Oracle Content Server and display the Admin Server page, you can view the Oracle Content Server log by selecting the Oracle Content Server instance and then clicking View Server Output.

  • You can view the Oracle Content Server log files in the DomainHome/ucm/cs/weblayout/groups/secure/logs directory.

1.4.2 Viewing Page Data

The IsJava setting displays the local data of an Oracle Content Server web page.

  • In a web browser, add the following code in the Address box to the end of the page's URL:

    &IsJava=1
    
  • On a template page or in an include, use the following code:

    <$IsJava=1$>
    

The IsPageDebug setting displays a tree structure view of all includes being called on an Oracle Content Server web page. The debug trace appears at the bottom of the web page.

  • In a web browser, add the following code in the Address box to the end of the page's URL:

    &IsPageDebug=1
    
  • On a template page or in an include, use the following code:

    <$IsPageDebug=1$>
    

    Tip:

    You can also set the IsPageDebug variable in the config.cfg file if you want the setting to apply for the whole server.
  • To place a marker in the script debug trace, place the following code at the point where you want to see a value or perform a step:

    <$trace("marker code")$>
    

    For example, you can use the following code to insert the current user name in the debug trace (the eval function must be used to evaluate Idoc Script):

    <$trace(eval("The user name is <$UserName$>")$>
    

IsJava and IsPageDebug are discussed in detail in the Oracle Fusion Middleware Idoc Script Reference Guide.

1.4.3 Monitoring Resource Loading

Three configuration settings enable you to view the loading of resources when you run Oracle Content Server from a command line. Set any of these variables equal to 1 in the IntradocDir/config/config.cfg file:

  • TraceResourceLoad logs all resources loaded, resource overrides, resource conflicts, and resource merges.

  • TraceResourceOverride logs when a system resource is overridden by a component resource or a component resource is loaded twice.

  • TraceResourceConflict logs when a system resource is overridden twice by component resources.

These configuration settings are discussed in detail in the Oracle Fusion Middleware Idoc Script Reference Guide.

The following example shows the command line output when TraceResourceLoad=1.

Loading Java Resources
Loading ConflictTester Component
Loading ConflictTester2 Component
Loading Compression Component
Merging  into Filters
*MERGE* [validateStandard, compression.ConversionParamsFilter, null, 1]
Loading Html Resources
Loading System Resource
c:/intradoc/shared/config/resources/upper_clmns_map.htm
ColumnTranslation
Loading System Resource
c:/intradoc/shared/config/resources/indexer.htm
IndexerQueryTable
IndexerStatesTable
IndexerTransitionsTable
DefaultIndexerCycles
Loading System Resource
c:/intradoc/shared/config/resources/std_page.idoc
std_html_head_declarations
std_definitions
std_html_head_definition_declarations
std_page_variable_definitions
…

Loading System Resource
c:/intradoc/shared/config/resources/std_docrefinery.htm
AdditionalRenditionsSource
DocumentConversions
ConversionSteps
Loading ConflictTester Component
c:/intradoc/custom/ConflictTester/resources/conflicttester_resource.htm
conflict_tester_include
ConflictTester_Table
Loading ConflictTester2 Component
c:/intradoc/custom/ConflictTester2/resources/conflicttester_resource.htm
*OVERRIDE* conflict_tester_include
***CONFLICT*** ConflictTester_Table
Loading Compression Component
c:/intradoc/custom/Compression/Compression_resource.htm
*OVERRIDE* searchapi_result_definitions
*OVERRIDE* searchapi_thumbnail_result_doc_href_start
*OVERRIDE* searchapi_result_table_content_begin
compression_thumbnail_img
Loading Compression Component
c:/intradoc/custom/Compression/Compression_handlers.htm
CompressionHandlers
Merging ConflictTester_Templates into IntradocTemplates
*MERGE* HOME_PAGE
Merging ConflictTester_Templates into IntradocTemplates
*MERGE* HOME_PAGE
Merging CompressionIntradocTemplates into IntradocTemplates
*MERGE* COMPRESSION_IMAGE_INFO
Merging CompressionHandlers into ServiceHandlers
*MERGE* [FileService, compression.CompressionFileServiceHandler, 100]
*MERGE* [FileService, DocCommonHandler, 100]
*MERGE* [DocService, compression.CompressionFileServiceHandler, 100]
…