3 Working with Standard, Server, and Custom Components

3.1.1 Component Wizard

The Component Wizard utility automates the process of creating custom components, including creating and editing all the files necessary for custom components. You can also use the Component Wizard to modify existing components and to package and unpackage components for use on Oracle Content Server instances.

The Component Wizard is discussed in more detail in the Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

Figure 3-1 Component Wizard Interface

To access the Component Wizard

• UNIX operating system: Run ComponentWizard, stored in DomainHome/ucm/short-product-id/bin/.

  The Component Wizard main page is displayed.

• Windows operating system: From the Start menu, choose the instance name, then Utilities, and then Component Wizard.

  The Component Wizard main page is displayed.

3.1.2 Advanced Component Manager

The Advanced Component Manager provides a way to manage custom components in Oracle Content Server. By using the Advanced Component Manager, you can easily enable or disable components or add new components to Oracle Content Server.

The Advanced Component Manager is discussed in more detail in the Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

To use the Advanced Component Manager:

1. In the Administration tray or menu, choose Admin Server.

   The Admin Server displays the Component Manager page, which has lists of enabled and disabled components.

2. In the first paragraph on the Component Manager page, click advanced component manager.

3. On the Advanced Component Manager page, you can do these tasks:

   • View lists of enabled and disabled components by categories and other filters

   • Select a component to view details about it

   • Enable components

   • Disable components

   • Install custom components

   • Uninstall custom components

Figure 3-2 Advanced Component Manager Page

3.1.3 ComponentTool

ComponentTool is a command-line utility for installing, enabling, and disabling components in Oracle Content Server. After installing a component, ComponentTool automatically enables it. ComponentTool is located in the DomainHome/ucm/cs/bin directory.

3.1.4 Component Files Overview

When you define a custom component, you create or make changes to the following files:

• The idcshort-product-id_components.hda file, which tells Oracle Content Server what components are enabled and where to find the definition file for each component.

• The component definition (or glue) file, which tells Oracle Content Server where to find the resources for the custom component.

• Different custom resource files, which define your customization to standard Oracle Content Server resources.

• Template files, which define custom template pages.

• Other files which contain customization to Oracle Content Server graphics, Java code, help files, and so on.

For more detailed information about these files, see Section 3.2, "About Directories and Files."

Any type of file can be included in a component, but the following file formats are used most often:

• HDA

• HTM

• CFG

• Java CLASS

If you build or unpackage components in the Component Wizard, or upload and download components in the Component Manager, you work with the following files:

• A compressed ZIP file used to deploy a component on other Oracle Content Server instances.

• A manifest.hda file that tells Oracle Content Server where to place the files that are unpackaged or uploaded from a component ZIP file.

3.1.5 Enabling and Disabling Components

By definition, a component is enabled when it is properly defined in the Components ResultSet in the idc_components.hda file. A component is disabled if there is no entry or the entry is not formatted correctly.

There are several ways to enable or disable a component:

• ComponentTool: Run DomainHome/ucm/short-product-id/bin/ComponentTool to enable or disable a component. For example:

  ComponentTool -enable component_name
  

• Component Wizard: Choose Enable or Disable from the Options menu. For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

• Component Manager: Select the checkbox next to a component name to enable a server component specified on the Component Manager screen. Clear the checkbox next to a component name to disable a server component on the Component Manager screen. For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

• Advanced Component Manager: On the Advanced Component Manager page, select a component name, and click Disable to disable the component, or click Enable to enable the component.

3.2.1 HDA Files

A HyperData File (HDA) is used to define properties and tabular data in a simple, structured ASCII file format. It is a text file that is used by Oracle Content Server to determine which components are enabled and disabled and where to find the definition files for that component.

The HDA file format is useful for data that changes frequently because the compact size and simple format make data communication faster and easier for Oracle Content Server.

The HDA file type is used to define the following component files:

• Components file (idc_components.hda)

• Component definition file

• Manifest file

• Dynamic table resource file

• Template resource file

The following example file is an idccs_components.hda file that points to a component called customhelp.

<?hda charset=Cp1252 encoding=iso-8859-1?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
@end
@ResultSet Components
2
name
location
customhelp
custom/customhelp/customhelp.hda
@end

@properties LocalData
blDateFormat=M/d/yy 
@end
@ResultSet Components
2
name
location
SchemaDCL
custom/SchemaDCL/SchemaDCL.hda
ConfigMigrationUtility
custom/ConfigMigrationUtility/Cmu.hda
Soap
custom/Soap/Soap.hda
@end

<?hda version="5.1.1 (build011203)" jcharset=Cp1252 encoding=iso-8859-1?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
blFieldTypes=
@end
@ResultSet ResourceDefinition
4
type
filename
tables
loadOrder
environment
customhelp_environment.cfg
null
1
@end

3.2.2 Custom Resource Files

Custom resource files define your Oracle Content Server customization. They are usually HDA files but some are HTM files.

The custom resource files for a component are typically located in the DomainHome/ucm/short-product-id/custom/component_name directory. Some resource files may be placed in subdirectories such as resources/core/templates.

The following table describes these resources.

For more detailed information about these files, see Section 3.5, "Resources Detail."

In addition, a template.htm page is used by Oracle Content Server to assemble web pages. For more detailed information about the template.hdm file, see Section 3.5.8, "Templates."

A ResultSet HTM table file is used by other resources. A ResultSet table in an HTM file is similar to the ResultSet of an HDA file, except that it uses HTML table tags to lay out the data. Static table resources, service resources, and query resources all use this table format.

A ResultSet table in an HTM file begins with <@table table_name@> and ends with <@end@>. The markup between the start and end tags is an HTML table. Unlike a ResultSet in an HDA file, the number of columns is implied by the table tags.

Any HTML syntax that does not define the data structure is ignored when the table is loaded. Therefore, HTML comments are allowed within tables in an HTM file, and HTML style attributes can be used to improve the presentation of the data in a web browser.

3.2.3 Data Binder

Oracle Content Server caches data (such as variable values and lookup keys) internally in a data binder. All data in the data binder is categorized according to where it came from and how it was created. When a value is required to fulfill a service request, the data in the data binder is evaluated in the following default order:

1. LocalData

2. ResultSets

3. Environment

This precedence can be changed using Idoc Script functions. For more information, see the Oracle Fusion Middleware Idoc Script Reference Guide.

3.2.4 Manifest File

Manifest files are used to upload or unpackage a component ZIP file on Oracle Content Server. This file tells Oracle Content Server where to place the individual files that are included in the component ZIP file. A manifest file is created automatically when you build a component in the Component Wizard, or when you download a component using the Admin Server Advanced Component Manager.

All manifest files must be called manifest.hda. The manifest.hda file is included in the component ZIP file along with the other component files. It must be at the top level of the ZIP file directory structure.

The manifest.hda file contains a ResultSet table called Manifest, which consists of two columns:

• The entryType column defines the type of entry in the manifest file.

  Entry Type	Description	Default Path
  Classes	Java class files	DomainHome/ucm/short-product-id/classes
  Common	Common files	DomainHome/ucm/short-product-id/weblayout/common
  Component	Component resource files	DomainHome/ucm/short-product-id/custom
  ComponentExtra	Associated files, such as a readme	DomainHome/ucm/short-product-id/custom
  Help	Online help files	DomainHome/ucm/short-product-id/weblayout/help
  Images	Graphics files	DomainHome/ucm/short-product-id/weblayout/images
  Jsp	JavaServer Pages	DomainHome/ucm/short-product-id/weblayout/jsp

  
  

  Caution:

  Avoid using the entry types Common, Help, Images, and Jsp because they are deprecated in Oracle UCM 11g. Oracle UCM has a publishing engine that pushes files into the weblayout directory from components. If you want the same behavior as in a previous release, use the publishing engine; otherwise, the publishing engine may place files directly into the weblayout directory from a custom component, overwriting existing files. The overwritten files could be permanently lost.

• The location column defines the directory where the files associated with the entry are installed and specifies the file name for some entry types.

  • For a Component entry type, the location is the path and file name for the definition file. The definition file then tells Oracle Content Server which resource files are included in the component.

  • For other entry types, the location can be a path without a file name (to specify all files in a particular subdirectory) or a path with a file name (to specify an individual file).

  • The location should be a path relative to the DomainHome/ucm/short-product-id/custom directory. You can use an absolute path, but then the component can be installed only on Oracle Content Server instances with the same installation directory path.

An example of a manifest.hda file follows:

@ResultSet Manifest
2
entryType
location
component
MyComponent/MyComponent.hda
componentExtra
MyComponent/readme.txt
images
MyComponent/
@end

3.2.5 Other Files

Your custom components can include any type of file that Oracle Content Server uses for functionality or to generate its look and feel.

3.2.6 Typical Directory Structure

If you use the Component Wizard to create custom components, your files are stored in the appropriate directory.

Different component directories are established for each custom component in the DomainHome/ucm/short-product-id/custom directory. Within each component directory, separate subdirectories are established for reports, templates, and resources, all named appropriately (for example, component_name/resources/). The component_name.hda file (the definition file) is stored in the component_name directory.

3.3.1 Creating a Component

To create and enable a custom component, follow this basic procedure:

1. Create a definition file.

2. Add a reference to the definition file in the idcshort-product-id_components.hda file to enable the component.

3. Restart Oracle Content Server to apply the component.

4. Create resources and other files to define your customization. A good approach is to copy, rename, and modify standard Oracle Content Server files to create your custom resource files.

5. Test and revise your customization as necessary. You may need to restart Oracle Content Server to apply your changes.

6. If you want to package the component for later use or for deployment on other Oracle Content Servers instances, build the component and create a component ZIP file.

3.3.2 Working with Component Files

Two tools are available for working with component files:

• Component Wizard

  The Component Wizard is an Oracle Content Server utility that can help you create and edit component files. You can also use the Component Wizard to package, unpackage, enable, and disable components. For more information about using this utility, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

• Text editor

  Because most component files are plain text files, you can create and edit the files in your favorite text editor.

You should use the Component Wizard as much as possible when working with custom components.

The Component Wizard does several tasks for you and minimizes the amount of work you need to do in a text editor. Using the Component Wizard helps you follow the recommended file structure and naming conventions. The Component Wizard automatically adds a readme text file when you build a component, thus helping you to document your customization. You should also include comments within your component files.

For information about using the Component Wizard to create components, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

3.3.3 Using a Development Instance

Whenever you are customizing Oracle Content Server, you should isolate your development efforts from your production system. Remember to include the same custom metadata fields on your development instance as you have defined for your production instance.

When you have successfully tested your modifications on a development instance, use the Component Wizard to build a component ZIP file and then unpackage the component on your production system.

Remember to restart Oracle Content Server after enabling or disabling a component.

If you are having problems with your Oracle Content Server instance after you have installed a custom component, disable the component and restart the instance. If this fixes the problem, you probably need to troubleshoot your component. If the problem is not fixed, you may need to remove the component completely using the Component Wizard to determine whether there is a problem with the component or with the Oracle Content Server instance.

3.3.4 Component File Organization

To keep your custom components organized, follow these file structure guidelines. For more information, see Section 3.2.6, "Typical Directory Structure."

Place each custom component in its own directory within a directory called DomainHome/ucm/short-product-id/custom. If your custom component includes resource-type or template-type resources, or both, the component directory should have subdirectories that follow the structure of the IdcHomeDir/data/resources/core directory:

• resources to hold HTML include and table resource files

• resources/lang to hold string resource files

• templates to hold template files

• reports to hold report files

Keep the following points in mind when considering files and their organization:

• Place the definition file for each custom component at the top level of the component's directory.

• When referring to other files within a component, use relative path names instead of absolute path names. Using relative path names enables you to move the component to a different location without having to edit all of the files in the component.

• Oracle Content Server is a Java-based application, so forward slashes must be used in all path names.

• Custom components do not have to be stored on the same computer as Oracle Content Server, but all component files must be accessible to your Oracle Content Server instance.

• Images and other objects that are referenced by Oracle Content Server web pages must reside somewhere in the DomainHome/ucm/short-product-id/weblayout directory (so they can be accessed by the web server).

3.3.5 Naming Conventions

To keep your component files organized and ensure that the files work properly in Oracle Content Server, follow these naming conventions for directories, individual files, and file contents.

• You should give all of your component directories and files unique and meaningful names. Keep in mind that as each component is loaded into Oracle Content Server, it overrides any resources with the same file names, so you should use duplicate file names only if you want certain components to take precedence.

• If you are copying a standard Oracle Content Server file, a common practice is to place the prefix custom_ in front of the original file name. This ensures that you do not overwrite any default templates, and your customization is easy to identify.

• HTM file types should have an .htm extension, and HDA file types should have an .hda extension.

• If you are creating a new component file with a text editor, like WordPad, place the file name within quotation marks in the Save dialog box so the proper file extension is assigned to it (for example, myfile.hda). Failure to use quotation marks to define the file name may result in a file name such as myfile.hda.txt.

• Oracle Content Server is case sensitive even if your file system is not. For example, if a file is named My_Template, Oracle Content Server does not recognize case variations such as my_template or MY_TEMPLATE.

• For localized string resources, you must follow the standard file naming conventions for Oracle Content Server to recognize the strings. You should also use the standard two-character prefix (cs, sy, ap, or ww) when naming your custom strings. For more information, see Section 2.3.6, "Localized String Resolution."

3.4.1 The idc_components.hda File

The idc_components.hda file tells Oracle Content Server which components are enabled and where to find the component definition (glue) file for each component. In 11g Release 1 (11.1.1), this file has three forms, one for each of the Oracle UCM products: idccs_components.hda (for Oracle Content Server), idcibr_components.hda (for Oracle Inbound Refinery), and idcurm_components.hda (for Oracle Universal Records Management). The file is always stored in the IntradocDir/data/components directory.

<?hda version="5.1.1 (build011203)" jcharset=Cp1252 encoding=iso-8859-1?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
blFieldTypes=
@end
@ResultSet Components
2
name
location
MyComponent
custom/MultiCheckin/my_component.hda
CustomHelp
custom/customhelp/customhelp.hda
@end

3.4.2 Component Definition (Glue) File

A component definition file, or glue file, points to the custom resources that you have defined. The definition file for a component is named component_name.hda, and is typically located in the DomainHome/ucm/short-product-id/custom/component_name directory. The Component Wizard can be used to create and make changes to a definition file.

A definition file contains a ResourceDefinition ResultSet and may contain a MergeRules ResultSet, a Filters ResultSet, a ClassAliases ResultSet, or any combination of these ResultSets. The following example shows a typical component definition file.

<?hda jcharset=UTF8 encoding=utf-8?>
@Properties LocalData
classpath=$COMPONENT_DIR/classes.jar
ComponentName=Custom DCL Component
serverVersion=7.3
version=2010_10_22
@end
@ResultSet ResourceDefinition
4
type
filename
tables
loadOrder
template
dcl_templates.hda
DCLCustomTemplates
1
resource
dcl_resource.htm
null
1
resource
dcl_upper_clmns_map.htm
DCLColumnTranslationTable
1
resource
dcl_data_sources.htm
dclDataSources
1
service
dcl_services.htm
CustomServices
1
query
dcl_query.htm
CustomQueryTable
1
resource
dcl_checkin_tables.hda
null
1
@end

@ResultSet MergeRules
3
fromTable
toTable
column
DCLCustomTemplates
IntradocTemplates
name
DCLColumnTranslationTable
ColumnTranslation
alias
DCLDataSources
DataSources
name
CustomDCLServiceQueries
ListBoxServiceQueries
dataSource
@end

@ResultSet Filters
4
type
location
parameter
loadOrder
loadMetaOptionsLists
intradoc.server.ExecuteSubServiceFilter
GET_CHOICE_LIST_SUB
1
@end

@ResultSet ResourceDefinition
4
type
filename
tables
loadOrder
template
dcl_templates.hda
DCLCustomTemplates
1
resource
dcl_resource.htm
null
1
resource
dcl_upper_clmns_map.htm
DCLColumnTranslationTable
1
resource
dcl_data_sources.htm
dclDataSources
1
service
dcl_services.htm
CustomServices
1
query
dcl_query.htm
CustomQueryTable
1
resource
dcl_checkin_tables.hda
null
1
@end

@ResultSet MergeRules
4
fromTable
toTable
column
loadOrder
DCLCustomTemplates
IntradocTemplates
name
1
DCLColumnTranslationTable
ColumnTranslation
alias
1
DCLDataSources
DataSources
name
1
CustomDCLServiceQueries
ListBoxServiceQueries
dataSource
1
@end

@ResultSet Filters
4
type
location
parameter
loadOrder
loadMetaOptionsLists
intradoc.server.ExecuteSubServiceFilter
GET_CHOICE_LIST_SUB
1
@end

@ResultSet ClassAliases
2
classname
location
WorkflowDocImplementor
WorkflowCheck.CriteriaWorkflowImplementor
@end

3.5.1 HTML Include

An include is defined within <@dynamichtml name@> and <@end@> tags in an HTM resource file. The include is then called using this syntax:

<$include name$>

Includes can contain Idoc Script and valid HTML code, including JavaScript, Java applets, cascading style sheets, and comments. Includes can be defined in the same file as they are called from, or they can be defined in a separate HTM file. Standard HTML includes are defined in the IdcHomeDir/resources/core/idoc files.

HTML includes, strings, and static tables can be present in the same HTM file. An HTML include resource does not require merge rules.

<@dynamichtml my_resource@>
    <$include super.my_resource$>
    exception code
<@end@>

<@dynamichtml my_resource@>
    <$a = 1, b = 2$>
<@end@>

<@dynamichtml my_resource@>
    <$include super.my_resource$>
    <!--Change "b" but not "a" -->
    <$b = 3$>
<@end@>

3.5.2 Dynamic Data Tables

A dynamic data table resource is a dynamicdata table. This type of resource enables you to define tables of data 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.

While tables loaded into SharedObjects are static and rarely change, a lot of code within Oracle Content Server will modify the contents of a dynamicdata table when it is loaded into a user's context. You can use dynamicdata resources to display different data to users depending on anything from their security attributes to the specific actions they are performing. Components can do targeted merging into tables created with this resource type, and Idoc Script pages can select and sort rows.

You can declare a dynamicdata resource as follows in any resource file that can contain dynamichtml constructions:

<@dynamicdata NameOfTable@>
<?formatoftable properties-of-table?>
table-data
<@end@>

A dynamicdata table is defined within <@dynamicdata name@> and <@end@> tags in a resource file. To reference dynamicdata tables, you need to use the Idoc Script functions whose names begin with dd, such as ddLoadResultSet, which loads a merged dynamicdata table and creates a ResultSet in the current data binder.

The IdcHomeDir/resources/core/idoc files define standard dynamicdata resources.

<@dynamicdata SampleTable@>
<?commatable?>
col1,   col2
val1_1, val1_2
val2_1, val2_2
<@end@>

<@dynamicdata SampleTable@>
field1, field2
A^B,    C##^D#^E#F^G
<@end@>

<@dynamicdata SampleTable@>
<?htmltable?>
<table>
<tr>
        <td>col1</td>
        <td>col2</td>
</tr>
<tr>
        <td>val11</td>
        <td>val12</td>
</tr>
<tr>
        <td>val21</td>
        <td>val22</td>
</tr>
</table>
<@end@>

field1="value1" field2="value2" . . .

<@dynamicdata ExampleTable@>
<?commatable mergeField="fieldA" indexedColumns="fieldA,fieldB"?>
fieldA, fieldB
1,      2
3,      4
<@end@>

<@dynamicdata ExampleTable@>
<?commatable mergeField="fieldA" indexedColumns="fieldA,fieldB" notrim?>
fieldA, fieldB
1, 2
3, 4
<@end@>

3.5.3 String

A string resource defines locale-sensitive text strings that are used in error messages and on Oracle Content Server web pages and applets. Strings are resolved by Oracle Content Server each time a web page is assembled, an applet is started, or an error message is displayed.

A string is defined in an HTM file using the following format:

<@stringID=Text string@>

A string is called from an HTM template file using the following Idoc Script format:

<$lc("wwStringID")$>

Standard English strings are defined in the IdcHomeDir/resources/core/lang directory. Strings for other supported languages are provided by the Localization component.

HTML includes, strings, and static tables can be present in the same HTM file. A string resource does not require merge rules.

You must use HTML escape encoding to include the following special characters in a string value.

You can specify strings for multiple languages in the same resource file using the language identifier prefix, if the languages all have single-byte characters or all have multibyte characters. For example:

<@myString=Thank you@>
<@es.myString=Gracias@>
<@fr.myString=Merci@>
<@de.myString=Danke@>

If you are specifying multibyte strings in your custom string resource, ensure that the character set specification on your HTML pages changes to the appropriate encoding. Resource files should have a correct http-equiv charset tag so that Oracle Content Server reads them correctly.

3.5.4 Dynamic Tables

Dynamic table resources are defined in the HDA file format. For more information and an example of an HDA ResultSet table, see Section 3.2.1.1, "Elements in HDA Files."

3.5.5 Static Tables

Static tables, HTML includes, and strings can be present in the same HTM file.

3.5.6 Query

A query resource defines SQL queries, which are used to manage information in the Oracle Content Server database. Queries are used with service scripts to perform tasks such as adding to, deleting, and retrieving data from the database.

The standard Oracle Content Server queries are defined in the QueryTable table in the IdcHomeDir/resources/core/tables/query.htm file. You also find special-purpose queries in the indexer.htm and workflow.htm files that are stored in the IdcHomeDir/resources/core/tables directory. Merge rules are not required for a query resource.

A query resource is defined in an HTM file using a ResultSet table with three columns: name, queryStr, and parameters.

• The name column defines the name for each query. To override an existing query, use the same name for your custom query. To add a new query, use a unique query name. When naming a new query, identify the type of query by starting the name with one of the following characters.

  First Character	Query Type
  D	Delete
  I	Insert
  Q	Select
  U	Update

  
  

• The queryStr column defines the query expression. Query expressions are in standard SQL syntax. If there are any parameter values to pass to the database, their place is held with a question mark (?) as an escape character.

• The parameters column defines the parameters that are passed to the query from a service. A request from a web browser calls a service, which in turn calls the query. It is the responsibility of the web browser to provide the values for the query parameters, which are standard HTTP parameters The browser can pass query parameters from the URL or from FORM elements in the web page. For example, the QdocInfo query requires the dID (revision ID) to be passed as a parameter, so the value is obtained from the service request URL.

3.5.6.1 Query Example

The following example shows the standard QdocInfo query as defined in the IntradocDir/shared/config/resources/query.htm file. This query obtains the metadata information to display on the DOC_INFO template page, which is the page displayed when a user clicks the Information icon on a search results page.

The parameter passed from the web browser URL is the dID, which is the unique identification number for the content item revision. The query expression selects the data that matches the dID for the primary revision from the Revisions, Documents, and DocMeta database tables, if the revision does not have the DELETED status.

Figure 3-3 Standard QDocInfo Query

<HTML>
<HEAD>
<META HTTP-EQUIV='Content-Type' content='text/html; charset=iso-8859-1'>
<TITLE>Query Definition Resources</TITLE>
</HEAD>
<BODY>
<@table QueryTable@>
<table border=1><caption><strong>Query Definition Table</strong></caption>
<tr>
    <td>name</td>
    <td>queryStr</td>
    <td>parameters</td>
</tr>
<tr>
    <td>QdocInfo</td>
    <td>SELECT Revisions.*, Documents.*, DocMeta.*
    FROM Revisions, Documents, DocMeta
    WHERE Revisions.dID=? AND Revisions.dID=Documents.dID AND DocMeta.dID = Documents.dID AND Revisions.dStatus<>'DELETED' AND Documents.dIsPrimary<>0</td>
    <td>dID int</td>
</tr>
</table>
<@end@>
</BODY>
</HTML>

3.5.7 Service

A service resource defines a function or procedure that is performed by Oracle Content Server. A service call can be performed from either the client or server side, so services can be performed on behalf of the web browser client or within the system itself. For example:

• Client-side request: When you click a Search link on an Oracle Content Server web page, the standard search page is delivered to your web browser by the GET_DOC_PAGE service, using the following URL segment:

  IdcService=GET_DOC_PAGE&Action=GetTemplatePage&Page=STANDARD_QUERY_PAGE
  

• Server-side request: You can use the START_SEARCH_INDEX service to update or rebuild the search index automatically in a background thread.

Services are the only way a client can communicate with the server or access the database. Any program or HTML page can use services to request information from Oracle Content Server or perform a specified function.

The standard Oracle Content Server services are defined in the StandardServices table in the IdcHomeDir/resources/core/tables/std_services.htm file. You can also find special-purpose services in the workflow.htm file in the IdcHomeDir/resources/core/tables directory.

Services depend on other resource definitions to perform their functions. Any service that returns HTML requires a template to be specified. A common exception is the PING_SERVER service, which does not return a page to the browser.

Most services use a query. A common exception is the SEARCH service, which sends a request directly to the search collection. Merge rules are not required for a service resource.

The following table row is an example of a service definition.

Figure 3-4 Service Definition Example

A service resource is defined in an HTM file using a ResultSet table with the following three columns:

• The Name column defines the name for each service. For client-side service requests, this is the name called in the URL. To override an existing service, use the same name for your custom service. To add a new service, use a unique service name.

• The Attributes column defines the following attributes for each service.

  Attribute	Description	Example (attributes from the DELETE_DOC service)
  Service class	Determines, in part, what actions can be performed by the service.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Access level	Assigns a user access level to the service. This number is the sum of the following possible bit flags: READ_PRIVILEGE = 1 WRITE_PRIVILEGE = 2 DELETE_PRIVILEGE = 4 ADMIN_PRIVILEGE = 8 GLOBAL_PRIVILEGE = 16 SCRIPTABLE_SERVICE=32	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Template page	Specifies the template that presents the results of the service. If the results of the service do not require presentation, this attribute is null.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Service type	If the service is to be executed inside another service, this attribute is SubService; otherwise, this attribute is null.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Subjects notified	Specifies the subjects (subsystems) to be notified by the service. If no subjects are notified, this attribute is null.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Error message	Defines the error message returned by the service if no action error message overrides it. This can be either an actual text string or a reference to a locale-sensitive string. For more information, see Section 2.3.6, "Localized String Resolution."	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)

  
  

• The Actions column defines the actions for each service. An action is an operation to be performed as part of a service script. The action can execute an SQL statement, perform a query, run code, cache the results of a query, or load an option list. Each service includes one or more actions, which specify what happens upon execution.

  The <br> tags in the Actions column are for browser display purposes only, so they are optional. However, the </td> tag must occur immediately after the actions, without a line break in between. An action is defined using the following format:

  type:name:parameters:control mask:error message
  

  Section	Description	Example (first action from the DELETE_DOC service)
  Type	Defines the type of action: QUERY_TYPE = 1 EXECUTE_TYPE = 2 CODE_TYPE = 3 OPTION_TYPE = 4 CACHE_RESULT_TYPE = 5	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExists
  Name	Specifies the name of the action.	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
  Parameters	Specifies parameters required by the action. If no parameters are required, leave this part empty (two colons appear in a row).	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
  Control mask	Controls the results of queries to the database. This number is the sum of the following possible bit flags: No control mask = 0 CONTROL_IGNORE_ERROR = 1 CONTROL_MUST_EXIST = 2 CONTROL_BEGIN_TRAN = 4 CONTROL_COMMIT_TRAN = 8 CONTROL_MUST_NOT_EXIST = 16	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
  Error message	Defines the error message to be displayed by this action. This error message overrides the error message provided as an attribute of the service. This can be either an actual text string or a reference to a locale-sensitive string. For more information, see Section 2.3.6, "Localized String Resolution."	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist

  
  

3.5.7.1 Service Example

The DOC_INFO service provides a good example of how services, queries, and templates work together. The following figures show the DOC_INFO service definition from the IntradocDir/config/resources/std_services.htm file.

Figure 3-5 DOC_INFO Service

<HTML>
    <HEAD>
    <META HTTP-EQUIV='Content-Type' content='text/html; charset=iso-8859-1'>
    <TITLE>Standard Scripted Services</TITLE>
    </HEAD>
    <BODY>
    <@table StandardServices@>
    <table border=1><caption><strong>Scripts For Standard Services</strong></caption>
    <tr>
    <td>Name</td><td>Attributes</td><td>Actions</td>
    </tr>
    <tr>
    <td>DOC_INFO</td>
    <td>DocService
        33
        DOC_INFO
        null
        null<br>
        !csUnableToGetRevInfo</td>
    <td>5:QdocInfo:DOC_INFO:2:!csItemNoLongerExists2
        3:mapNamedResultSetValues:DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle:0:null
        3:checkSecurity:DOC_INFO:0:!csUnableToGetRevInfo2(dDocName)
        3:getDocFormats:QdocFormats:0:null
        3:getURLAbsolute::0:null
        3:getUserMailAddress:dDocAuthor,AuthorAddress:0:null
        3:getUserMailAddress:dCheckoutUser,CheckoutUserAddress:0:null
        3:getWorkflowInfo:WF_INFO:0:null
        3:getDocSubscriptionInfo:QisSubscribed:0:null
        5:QrevHistory:REVISION_HISTORY:0:!csUnableToGetRevHistory(dDocName)</td>
    </tr>
    </table>
    <@end@>
    </BODY>
    </HTML>

3.5.7.1.1 Attributes

The following table describes the attributes of the DOC_INFO service shown previously.

Attribute	Value	Description
Service class	DocService	This service is providing information about a content item.
Access level	33	32 = This service can be executed with the executeService Idoc Script function. 1 = The user requesting the service must have Read privilege on the content item.
Template page	DOC_INFO	This service uses the DOC_INFO template (doc_info.htm file). The results from the actions are merged with this template and presented to the user.
Service type	null	This service is not a subservice.
Subjects notified	null	No subjects are affected by this service.
Error Message	!csUnableToGetRevInfo	If this service fails on an English Oracle Content Server system, it returns this error message string: Unable to retrieve information about the revision

3.5.7.1.2 Actions

The DOC_INFO service executes the following actions:

• 5:QdocInfo:DOC_INFO:2:!csItemNoLongerExists2

  Action Definition	Description
  5	Cached query action that retrieves information from the database using a query.
  QDocInfo	This action retrieves content item information using the QDocInfo query in the query.htm file.
  DOC_INFO	The result of the query is assigned to the parameter DOC_INFO and stored for later use.
  2	The CONTROL_MUST_EXIST control mask specifies that either the query must return a record, or the action fails.
  !csItemNoLongerExists2	If this action fails on an English Oracle Content Server system, it returns this error message string: This content item no longer exists

  
  

• 3:mapNamedResultSetValues:DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  mapNamedResultSetValues	This action retrieves the values of dStatus and dDocTitle from the first row of the DOC_INFO ResultSet and stores them in the local data. (This increases speed and ensures that the correct values are used.)
  DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle	Parameters required for the mapNamedResultSetValues action.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:checkSecurity:DOC_INFO:0:!csUnableToGetRevInfo2(dDocName)

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  checkSecurity	This action retrieves the data assigned to the DOC_INFO parameter and evaluates the assigned security level to verify that the user is authorized to perform this action.
  DOC_INFO	Parameter that contains the security information to be evaluated by the checkSecurity action.
  0	No control mask is specified.
  !csUnableToGetRevInfo2(dDocName)	If this action fails on an English Oracle Content Server system, it returns this error message string: Unable to retrieve information for ''{dDocName}."

  
  

• 3:getDocFormats:QdocFormats:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getDocFormats	This action retrieves the file formats for the content item using the QdocFormats query in the query.htm file. A comma-delimited list of the file formats is stored in the local data as dDocFormats.
  QdocFormats	Specifies the query used to retrieve the file formats.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getURLAbsolute::0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getURLAbsolute	This action resolves the URL of the content item and stores it in the local data as DocUrl.
  blank	This action takes no parameters.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getUserMailAddress:dDocAuthor,AuthorAddress:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getUserMailAddress	This action resolves the e-mail address of the content item author.
  dDocAuthor,AuthorAddress	This action passes dDocAuthor and AuthorAddress as parameters.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getUserMailAddress:dCheckoutUser,CheckoutUserAddress:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getUserMailAddress	This action resolves the e-mail address of the user who has the content item checked out.
  dCheckoutUser,CheckoutUserAddress	This action passes dCheckoutUser and CheckoutUserAddress as parameters.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getWorkflowInfo:WF_INFO:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getWorkflowInfo	This action evaluates whether the content item is part of a workflow. If the WF_INFO ResultSet exists, then workflow information is merged into the DOC_INFO template.
  WF_INFO	This action passes WF_INFO as a parameter.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getDocSubscriptionInfo:QisSubscribed:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getDocSubscriptionInfo	This action evaluates if the current user has subscribed to the content item: If the user is subscribed, an Unsubscribe button is displayed. If the user is not subscribed, a Subscribe button is displayed.
  QisSubscribed	Specifies the query used to retrieve the subscription information.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 5:QrevHistory:REVISION_HISTORY:0:!csUnableToGetRevHistory(dDocName)

  Action Definition	Description
  5	Cached query action that retrieves information from the database using a query.
  QrevHistory	This action retrieves revision history information using the QrevHistory query in the query.htm file.
  REVISION_HISTORY	The result the query is assigned to the parameter REVISION_HISTORY. The DOC_INFO template uses this parameter in a loop to present information about each revision.
  0	No control mask is specified.
  !csUnableToGetRevHistory(dDocName)	If this action fails on an English Oracle Content Server system, it returns the error message string: Unable to retrieve revision history for ''{dDocName}.''

  
  

3.5.8 Templates

A template resource defines the names, types, and locations of custom template files to be loaded for the component.

The actual template pages (.htm files) are separate files that are referenced in the template resource file. Template HTM files contain the code that the Oracle Content Server uses to assemble web pages. HTML markup in a template file defines the basic layout of the page, while Idoc Script in a template file generates additional HTML code for the web page at the time of the page request. Because HTM template files contain a large amount of script that is not resolved by Oracle Content Server until the final page is assembled, these files are not viewable web pages.

The template type of HTM file is used to define the following component files:

• Template pages: Standard template pages are located in the IdcHomeDir/resources/core/templates directory.

• Report pages: Standard report pages are located in the IdcHomeDir/resources/core/reports directory.

A template resource (templates.hda) is defined in the HDA file format. The standard templates are defined in the IdcHomeDir/resources/core/templates/templates.hda file. For more information and an example of an HDA ResultSet table, see Section 3.2.1.1, "Elements in HDA Files."

Merge rules are required to merge the new template definition into the IntradocTemplates table or the SearchResultTemplates table. Typically, the merge is on the name column. The following example shows a MergeRules ResultSet for a template.

@ResultSet MergeRules
4
fromTable
toTable
column
loadOrder
MultiCheckinTemplates
IntradocTemplates
name
1
@end

The standard templates.hda file defines three ResultSet tables:

• The IntradocTemplates ResultSet table defines the template pages for all Oracle Content Server web pages except search results pages. This table consists of five columns:

  • The name column defines the name for each template page. This name is how the template is referenced in the Oracle Content Server CGI URLs and in code.

  • The class column defines the general category of the template. The most common class type is Document.

  • The formtype column defines the specific type of functionality the page is intended to achieve. The formtype is typically the same as the name of the form, except in lowercase characters.

  • The filename column defines the path and file name of the template file. The location can be an absolute path or can be relative to the template resource file when the template page is in the same directory as the template resource file.

  • The description column defines a description of the template.

• The VerifyTemplates ResultSet table is no longer used by Oracle Content Server, but this table remains in the templates.hda file as legacy code for reverse compatibility.

• The SearchResultTemplates table defines the template pages for search results pages. Template pages define how query results are displayed on the search results pages in the Library. Query result pages are a special type of search results page. This table consists of six columns:

  • The name column defines the name for each template page. This name is how the template is referenced in the Oracle Content Server CGI URLs, in code, and in the Web Layout Editor utility.

    Note:

    The StandardResults template (search_results.htm file) is typically used as the global template for standard search results pages and the query results pages in the Library. You can create a new template or change the "flexdata" of the StandardResults template through the Web Layout Editor, but these changes are saved in a separate file (IntradocDir/data/results/custom_results.hda) rather than in the SearchResultTemplates table in the templates.hda file.

  • The formtype column defines the specific type of functionality the page is intended to achieve. ResultsPage is the only form type currently supported for search results pages.

  • The filename column defines the path and file name of the template file. The location can be an absolute path or can be relative to the template resource file when the template page is in the same directory as the template resource file.

  • The outfilename column is for future use; the value is always null.

  • The flexdata column defines the metadata to be displayed for each row on the search results page. The format of text in the flexdata column follows:

    Text1 "text 1 contents"%<Tab>Text2 "text 2 contents"%
    

    In the format, the Text1 value appears on the first line in each search results row, and the Text2 value appears on the second line. <Tab> represents a literal tab character.

    Idoc Script can be used to define the contents in the flexdata field. You can also change the flexdata of the StandardResults template through the Web Layout Editor, but these changes are saved in a separate file (IntradocDir/data/results/custom_results.hda) rather than in the SearchResultTemplates table in the templates.hda file.

  • The description column defines a description of the template.

The following example shows a custom template resource file that points to a custom Content Management page (multicheckin_doc_man.htm) and a custom search results page (MultiCheckin_search_results.htm).

<?hda version="5.1.1 (build011203)" jcharset=Cp1252 encoding=iso-8859-1?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
blFieldTypes=
@end
@ResultSet MultiCheckinTemplates
5
name
class
formtype
filename
description
DOC_MANAGEMENT_LINKS
DocManagement
DocManagementLinks
multicheckin_doc_man.htm
Page containing links to various document management functions
@end
@ResultSet MultiCheckin_2
6
name
formtype
filename
outfilename
flexdata
description
StandardResults
SearchResultsPage
MultiCheckin_search_results.htm
null
Text2 <$dDocTitle$> <$dInDate$>%       Text1 <$dDocName$>%
apStandardResultsDesc
@end

3.5.8.1 Template and Report Pages

Template pages and report pages are also called presentation pages, because Oracle Content Server uses them to assemble, format, and present the results of a web page request.

The standard template pages are located in the IdcHomeDir/resources/core/templates directory. The standard report pages are located in the IdcHomeDir/resource/core/reports directory.

3.5.8.1.1 Template Page Example

The following example shows the template file for the standard Content Management page (doc_man.htm).

Figure 3-6 Template Page Example

Description of "Figure 3-6 Template Page Example"

3.5.8.1.2 Report Page Example

The following example shows the template file for the standard Document Types report page (doc_types.htm).

Figure 3-7 Report Page Example

Description of "Figure 3-7 Report Page Example"

3.5.9 Environment

An environment resource defines configuration variables, either by creating new variable values or replacing existing values. Because custom resources are loaded after the standard config.cfg file is loaded, the variable values defined in the custom environment resource replace the original variable values.

An environment resource is defined in a CFG file using a name/value pair format:

variable_name=value

After defining a variable value, you can reference the variable in templates and other resource files with the following Idoc Script tag:

<$variable_name$>

Environment resource files can include comment lines, which are designated with a # symbol:

#Set this variable to true to enable the function.

# Use this to turn on or off alternate row coloring
nsUseColoredRows=0

# These are the nested search field definitions.

nsFld1Caption=Document Text
nsFld1Name=
nsFld1Type=FullText
nsFld1OptionKey=
#
nsFld2Caption=Text
nsFld2Name=xtext
nsFld2Type=Text
nsFld2OptionKey=
#
nsFld3Caption=Date
nsFld3Name=xdate
nsFld3Type=Date
nsFld3OptionKey=
#
nsFld4Caption=Integer
nsFld4Name=xinteger
nsFld4Type=Int
nsFld4OptionKey=
#
nsFld5Caption=Option List
nsFld5Name=xoptionlist
nsFld5Type=OptionList
nsFld5OptionKey=optionlistList
#
nsFld6Caption=Info Topic
nsFld6Name=xwfsInfoTopic
nsFld6Type=OptionList
nsFld6OptionKey=wfsInfoTopicList

<$if isTrue(#active.nsUseColoredRows)$>
    <$useColoredRows=1, bkgHighlight=1$>
<$endif$>

3.6.1 Installing a Component with Component Manager

Follow these steps to install the component using the Component Manager:

1. Select Admin Server from the Administration tray.

   The Admin Server page is displayed with the Advanced Component Manager screen.

2. Click the Browse button, and find the ZIP file that was downloaded and saved.

3. Highlight the component name, and click Open.

4. Click Install. A message is displayed, detailing what will be installed.

5. Click Continue to continue with installation or Cancel to stop installation.

6. If you click Continue, a message appears after successful installation. You can select one of two options:

   • To enable the component and restart Oracle Content Server.

   • To return to the Component Manager, where you can continue adding components. When done, highlight the components you want to enable, and click Enable. When finished enabling components, restart the server.

3.6.2 Installing a Component with Component Wizard

Follow these steps to install the component using the Component Wizard:

1. Start the Component Wizard:

   • (Windows operating system) From the Start menu, choose Programs, then Oracle Content Server, then your server instance, then Utilities, and then Component Wizard.

   • (UNIX operating system) Run the ComponentWizard script in the DomainHome/ucm/cs/bin directory.

   The Component Wizard main screen and the Component List screen are displayed.

2. On the Component List screen, click Install.

   The Install screen is displayed.

1. Click Select.

2. Navigate to the ZIP file that was downloaded and saved, and select it.

3. Click Open.

   The ZIP file contents are added to the Install screen list.

4. Click OK. You are prompted to enable the component.

5. Click Yes. The component is listed as enabled on the Component List screen.

6. Exit the Component Wizard.

7. Restart Oracle Content Server.

Depending on the component being installed, a new menu option appears in the Administration tray or on the Admin Applet page. Some components simply extend existing functionality and do not appear as separate new options. For more information, see the component's documentation.

3.6.3 Installing a Component with ComponentTool

Run the ComponentTool utility and specify the ZIP file for the component to install and enable:

DomainHome/ucm/cs/bin/ComponentTool path_to_file/component.zip