2 Oracle UCM Architecture

This chapter describes the architecture of Oracle Universal Content Management (Oracle UCM) in the context of what you need to know before beginning a customization project. To create a customization efficiently and effectively, you should have an understanding of how Oracle UCM works.

This chapter includes the following sections:

• Section 2.1, "Oracle UCM Directories and Files"

• Section 2.2, "Resources"

• Section 2.3, "Oracle Content Server Behavior"

2.1 Oracle UCM Directories and Files

When you create custom components or dynamic server pages, you work primarily with files in the bin, config, components, resources, and weblayout directories. The following sections describe these directories:

• Section 2.1.1, "Terminology for Oracle UCM Directories"

• Section 2.1.2, "The bin Directory"

• Section 2.1.3, "The config Directory"

• Section 2.1.4, "The components Directory"

• Section 2.1.5, "The resources Directory"

• Section 2.1.6, "The weblayout Directory"

  Caution:

  Modifying the default variables in these files can cause Oracle UCM to malfunction. For more information about configuration variables, see the Oracle Fusion Middleware Idoc Script Reference Guide.

2.1.1 Terminology for Oracle UCM Directories

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

• IdcHomeDir: This variable refers to the ucm/idc directory in the ECM Oracle home where the Oracle UCM server media is located. The server media can run Oracle Content Server, Oracle Inbound Refinery, or Oracle Universal Records Management. This is essentially a read-only directory. The default location is ECM_ORACLE_HOME/ucm/idc. The variable portion of the default location can be changed, but the path cannot be changed at ucm/idc.

• DomainHome: The user-specified directory where an Oracle UCM server is deployed to run on an Oracle WebLogic Server 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 Oracle UCM to Oracle WebLogic Server.

• short-product-id: An abbreviated name for the type of Oracle UCM server deployed to an Oracle WebLogic Server domain, and it is used as the context root (default HttpRelativeWebRoot configuration value). Possible values follow:

  • cs (Oracle Content Server)

  • ibr (Oracle Inbound Refinery)

  • urm (Oracle Universal Records Management)

• IntradocDir: The root directory for configuration and data files specific to an Oracle Content Server instance that is part of an Oracle UCM application deployed to an Oracle WebLogic Server domain. This Idoc Script variable is configured for one type of Oracle Content Server instance: Oracle Content Server (cs), Oracle Inbound Refinery (ibr), or Oracle Universal Records Management (urm). This directory can be located elsewhere, but the default location is DomainHome/ucm/short-product-id/. The specified directory must be an absolute path to the instance directory, and it must be unique to a particular server or node. The directory files include startup files (intradoc.cfg and executables).

2.1.2 The bin Directory

The bin directory is the root directory for Oracle Content Server startup files. It contains the intradoc.cfg file and the executable files that run Oracle 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 Oracle Content Server, Oracle Inbound Refinery, or Oracle Universal Records Management.

Element	Description
Executables	Services IdcServer IdcServerNT Applets IntradocApp (launches all Admin tools) Utilities Batch Loader Installer IdcAnalyze Component Wizard System Properties IdcCommand
intradoc.cfg file	Configuration file that contains the settings for Oracle Content Server services, applets, and utilities.

Note:

If Oracle Content Server is set up as an automatic service and you attempt to start an Oracle 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 Oracle Content Server, including directory, Internet, and refinery settings. Several of these variables can be set using the Oracle Content Server System Properties utility.

A typical intradoc.cfg file follows:

<?cfg jcharset="Cp1252"?>
#Oracle 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

2.1.3 The config Directory

The config directory stores global configuration information for Oracle Content Server. This directory can be located elsewhere, but the default location is DomainHome/ucm/short-product-id/config.

Element	Description
config.cfg file	Defines system configuration variables.

The config.cfg file is used to define global variables for the Oracle Content Server system. Several of these variables can be set using the Oracle Content Server System Properties utility or by modifying the variables on the Admin Server General Configuration page.

A typical config.cfg file follows:

<?cfg jcharset="Cp1252"?>
#Oracle 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=[e-mail]
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

2.1.4 The components Directory

The IntradocDir/data/components directory contains the files that Oracle Content Server uses to configure system components.

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

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

<?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

2.1.5 The resources Directory

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

The resources/core directory contains files that Oracle Content Server uses to assemble web pages.

Element	Description
config	Holds base configuration files for Oracle Content Server.
idoc	Holds IdocScript dynamichtml and dynamicdata definitions.
install	Holds files used by the installer and related applications.
javascript	Holds files which are processed by the publishing engine and end up in the weblayout directory as raw javascript files.
jspserver	Holds jspserver xml files.
lang	Holds localized string definitions for Oracle Content Server.
reports	Holds templates for Oracle Content Server reports.
resources	Holds resource definitions (queries, page resources, services, and other resource data) for Oracle Content Server.
tables	Holds IdocScript resource table definitions.
templates	Holds templates for all Oracle Content Server pages (except reports).

The resources/admin directory contains the following resource types.

Element	Description
idoc	Holds IdocScript dynamichtml and dynamicdata definitions.
tables	Holds IdocScript resource table definitions.
templates	Holds templates for all Oracle Content Server pages (except reports).

2.1.6 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 Oracle Content Server web site.

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

2.2 Resources

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

Resources are a critical part of the Oracle 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 distinct categories, although the first five types listed in the following table are also called Resource-type resources.

Resource Type	Description	Example of Standard Resource
HTML Include	Defines pieces of HTML markup and Idoc Script code that are used on multiple Oracle 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 IdocScript 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 Oracle Content Server.	IdcHomeDir/resources/core/datastoredesign/columnIndexdList.hda
Static Table (HTML format)	Provides static (seldom changed) content in table format to Oracle Content Server.	IdcHomeDir/resources/core/std_locale.htm
Query	Defines database queries.	IdcHomeDir/resources/core/tables/query.htm
Service	Defines scripts for services that can be performed by Oracle Content Server.	IdcHomeDir/resources/core/tables/std_services.htm
Template	Defines templates, which contain the code that Oracle Content Server uses to assemble a particular web page.	IdcHomeDir/resources/core/templates/checkin_new.htm
Environment	Defines configuration settings for Oracle Content Server.	IntradocDir/config/config.cfg

2.3 Oracle Content Server Behavior

The following sections describe how Oracle Content Server behaves in different situations:

• Section 2.3.1, "Startup Behavior"

• Section 2.3.2, "Resource Caching"

• Section 2.3.3, "Oracle Content Server Requests"

• Section 2.3.4, "Page Assembly"

• Section 2.3.5, "Database Interaction"

• Section 2.3.6, "Localized String Resolution"

2.3.1 Startup Behavior

The following steps occur during Oracle Content Server startup:

1. Internal initialization occurs.

2. Configuration variables load.

3. Standard templates, resources, and reports load.

4. Custom components load (templates, resources, configuration variables, and reports).

Figure 2-1 illustrates these steps in a flowchart. Section 2.3.1.1, "Startup Steps," describes each step in more detail.

Figure 2-1 Oracle Content Server Startup Behavior

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

2.3.1.1 Startup Steps

Here are descriptions of the steps that an Oracle Content Server instance goes through during startup:

1. Internal Initialization Occurs: When Oracle Content Server initializes internally, the Java class files from Oracle Content Server are read and the Java Virtual Machine (JVM) is invoked. Any variables in the DomainHome/ucm/short-product-id/intradoc.cfg file initialize as well.

2. Configuration Variables Load: After initializing, Oracle 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 Content Server installation process, but you can modify this file in several ways:

   • By using the Admin Server General Configuration page, accessible from the Administration menu.

   • By using the System Properties option, which is available from the Start menu (in Windows) or by running the SystemProperties script, located in the bin directory of your installation (on a UNIX operating system).

   • By editing the configuration files directly.

   • By using a custom component.

   Any time changes are made to the config.cfg file, you must restart Oracle Content Server for the changes to take effect.

3. Standard Resources, Templates, and Reports Load: For Oracle Content Server to function properly, many standard resources, templates, and reports must be loaded. After the configuration settings have been loaded, Oracle 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 Oracle Content Server which templates to load, which in turn loads any standard resources referenced in the template and report pages.

4. Custom Components Load: Oracle Content Server loads resources in the order specified in the IntradocDir/custom/components.hda file.

2.3.1.2 Effects of Configuration Loading

It is important to understand the effect of the load order of the different configuration files because if a variable is set in more than file, the last variable loaded takes precedence. For example, the IntradocDir/config/config.cfg file is loaded first, and the IntradocDir/data/components/component_name/config.cfg file is loaded last, 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):

1. IntradocDir/config/config.cfg.

2. DomainHome/ucm/short-product-id/custom/component_name/*_environment.cfg. Some components may not have this file or it may be named environment.cfg.

3. IntradocDir/data/components/component_name/install.cfg.

4. IntradocDir/data/components/component_name/config.cfg.

5. DomainHome/ucm/short-product-id/bin/intradoc.cfg is reread at the end of startup to allow overrides to other settings.

If, for example, a variable was set in each of the files listed previously, the variable in component_name/config.cfg takes precedence.

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

To change a component variable, use the Advanced Component Manager and select Update Component Configuration. This displays values in the component_name/config.cfg file that are editable. Make the desired changes, and click Update.

You can also edit the configuration file manually. If a component is not displayed in the drop-down list or if the variables displayed do not include the one to change, make the change directly in one of the configuration files.

2.3.2 Resource Caching

Oracle Content Server handles caches template pages and resources as follows:

• When Oracle 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 config variable DisableSharedCacheChecking.

• If you change any other component files (including services, queries, environment variables, tables, components.hda file, and template.hda file), you must restart Oracle Content Server before the changes go into effect. This is because such changes could cause Oracle Content Server to malfunction if they were implemented immediately. You do not need to restart Oracle Content Server when changing strings; however, you must republish the ww_strings.js files by clicking publish dynamic files in the Weblayout Publishing area of the Admin Actions page. For more information, see Chapter 3, "Working with Standard, Server, and Custom Components."

2.3.3 Oracle Content Server Requests

When a web browser client sends an Oracle Content Server request to the web server, the instructions are typically communicated through URLs or form fields. The web server routes the request to Oracle Content Server, which then performs one or more of the following actions:

• Retrieves pages

  For more information, see Section 2.3.3.1, "Page Retrieval."

• Runs an Oracle Content Server service

  For more information, see Section 2.3.3.2, "Oracle Content Server Services."

• Runs a search engine service

  For more information, see Section 2.3.3.3, "Search Services."

Note:

Oracle Content Server uses the web server provided by Oracle WebLogic Server.

When an Oracle Content Server web page is requested, all of the necessary information can be sent to Oracle Content Server through the URL. A typical Oracle Content Server URL follows, the URL for the Home page:

http://cs.example.com/instancename/idcplg?IdcService=GET_DOC_PAGE&Action=GetTemplatePage&Page=HOME_PAGE

• http://cs.example.com/instancename is the web address of the Oracle Content Server instance.

• IdcService=GET_DOC_PAGE tells Oracle Content Server to execute the GET_DOC_PAGE service.

• Action=GetTemplatePage tells Oracle Content Server to return the results using a specified template page.

• Page=HOME_PAGE tells Oracle Content Server which template page to use.

• The question mark (?) indicates the end of the web server path and the beginning of Oracle Content Server instructions.

• Ampersands (&) are used as separators between Oracle Content Server instructions.

• You can include some Idoc Script variables in a URL to affect page display at the time of the page request. This is useful for troubleshooting or for temporary pages. For example, the following variables can be used for customization:

  • &StdPageWidth=1000

  • &dDocAuthor:isHidden

  • &dDocType=HRForm

Necessary information can also be sent to Oracle Content Server through form fields on the page. A typical Oracle Content Server form follows:

<form name=SubscriptionForm action="<$HttpCgiPath$>" Method="GET"">
<input type=hidden name=dID value="<$dID$>">
<input type=hidden name=dDocName value="<$dDocName$>">
<input type=hidden name=subscribeService value=SUBSCRIBE>
<input type=hidden name=exitUrl value="<$HttpCgiPath$>?IdcService=DOC_INFO&dID=<$dID$>&dDocName=<$dDocName$>">
<input type=hidden name=title value="Subscriptions">
<input type=hidden name=unsubscribeService value=UNSUBSCRIBE>
<$if ClientControlled$>
<input type=hidden name=ClientControlled value="<$ClientControlled$>">
<$endif$>
<$if DocHasSubscription$>
<input type=hidden name=IdcService value="UNSUBSCRIBE_FORM">
<input type=submit value="<$lc("wwUnsubscribe")$>">
<$else$>
<input type=hidden name=IdcService value="SUBSCRIBE_FORM">
<input type=submit value="<$lc("wwSubscribe")$>">
<$endif$>
</form>

2.3.3.1 Page Retrieval

When a web page is requested from Oracle Content Server, the page it returns is either static dynamic:

• Static page

  The content of a static web page is preformatted, and does not change from one request to the next. On some Oracle Content Server web sites, the only static page is the Guest Home page (DomainHome/ucm/short-product-id/weblayout/portal.htm).

• Dynamic page

  A dynamic web page is assembled at the time of the web server request, using Oracle Content Server services and templates to determine the content and formatting. For example, each user's portal design page is generated using an Oracle Content Server service called GET_PORTAL_PAGE and a template called PNE_PORTAL_DESIGN_PAGE.

2.3.3.2 Oracle Content Server Services

When a web browser requests a dynamic page from Oracle Content Server, the browser is actually placing a request for an Oracle Content Server service.

For example:

1. When a user clicks the Administration link in the navigation area, a request for the GET_ADMIN_PAGE service is sent to the web server.

2. The web server recognizes this request as an Oracle Content Server function, and sends the specific request to Oracle Content Server.

3. When Oracle Content Server has processed the request, it passes the result back to the web server. In the case of the Administration link, the GET_ADMIN_PAGE service:

   • Provides a login prompt if the user is not currently logged in.

   • Verifies that the user has the admin privilege.

   • Assembles the Administration page, using the ADMIN_LINKS template.

   • Returns the assembled web page to the web server.

4. The web server delivers the results of the Oracle Content Server service to the originating web browser client.

2.3.3.3 Search Services

A search request is a special kind of Oracle Content Server service. When Oracle Content Server receives a search request, it sends the request on to the search engine, using a search engine API. This service makes it possible to use different search engines with Oracle Content Server.

For example:

1. When a user clicks the Search button on the standard Search page, a request for the GET_SEARCH_RESULTS service is sent to the web server.

2. The web server recognizes the request as an Oracle Content Server function and sends the specific request to Oracle Content Server.

3. Oracle Content Server passes the request to the search engine that is configured for the Oracle Content Server instance.

4. The search engine returns the search results to Oracle Content Server.

5. Based on the user login and security permissions, Oracle Content Server assembles the search results page and returns it to the web server.

6. The web server delivers the results to the originating web browser client.

2.3.4 Page Assembly

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

• The structure and format of a web page is defined by a particular HTML template file in either the resources/admin/templates directory or the resources/core/reports directory.

• The templates reference resources, which 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:

• A standard page header

• A standard page beginning

• A standard page ending

Because all of the Oracle Content Server resources are cached in memory at startup, Oracle Content Server has a definition for the standard pieces that appear on the page. Oracle 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 Oracle Content Server. When one of these pages is requested by a web browser, Oracle 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 Oracle Content Server.

2.3.5 Database Interaction

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

Because of this case mapping issue, custom components created for an Oracle Content Server instance using one database might not work correctly on an Oracle 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 Oracle Content Server database fields (for example, if you create a component that accesses a custom table within the Oracle Content Server database).

For information about using the upper_clmns_map.htm file, see Section 5, "Modifying System Functionality."

2.3.6 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. Oracle 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.