3 Customizing Services

This chapter discusses the basic structure of services and covers the following topics:

3.1 Service Structure Overview

This section describes how standard services are implemented in the Oracle Content Server system. For information about calling services from other programs, see the chapter about integration methods in the Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management.

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

The standard Oracle Content Server services are defined in the StandardServices table in the IdcHomeDir/resources/core/templates/std_services.htm file. You can also find special-purpose services in the workflow.htm file in the same 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. However, the service resource must be listed as a table in the ResourceDefinition ResultSet.

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

Figure 3-1 Example of a Service Definition

Surrounding text describes Figure 3-1 .

3.1.1 Name

The Name column in the StandardServices table defines the name for each service. For client-side service requests, this is the name called in Calling Services Using Persistent URLs. For standard Web requests, this is almost always the URL to the Oracle Content Server Web page.

Figure 3-2 The Name Column of the DELETE_DOC Service Definition

Surrounding text describes Figure 3-2 .

3.1.2 Attributes

The Attributes column in the StandardServices table defines aspects of each service, discussed in the following sections:

Figure 3-3 The Attributes Column of the DELETE_DOC Service Definition

Surrounding text describes Figure 3-3 .

3.1.2.1 Service Class

The service class attribute specifies the Java class object that the service has access to. The classpath prefix intradoc.service is assumed unless a full path is given. The service class determines, in part, what actions can be performed by the service. The possible service classes are:

Service Class Description
ArchiveService Performs functions related to archiving.
BatchService Performs functions related to batch loading.
ChunkedService Performs functions related to HTTP file chunking for the upload and download of applets.
DocService Performs actions on documents. Examples are checkin, checkout, document information, and subscription services.
DocProfileService Performs actions on document profiles, such as adding, editing, and deleting profiles.
FileService Retrieves files from the Oracle Content Server.
IndexerService Performs functions related to indexing for search engine maintenance.
ListBoxService Downloads lists from the Oracle Content Server. For example, lists of users, dependent choice lists, and so forth.
LocaleService Performs functions specific to a user's location or environment (for example, used in internationalization to identify a user's location and provide string files in the appropriate language).
MetaService Manages metadata fields.
PageHandlerService Manages Library Web pages (created by Web Layout Editor).
PageRequestService Retrieves an HTML page.
ProjectService Manages Publisher projects.
ProviderManagerService Manages providers (an Application Programming Interface, or API, that establishes connection to outside entities).
SchemaService Manages the server-side publishing of JavaScript files of database tables, such as option lists.
SearchService Performs functions related to searching.
Service Performs a general service.
UserService Manages users.
WorkflowService Manages workflows.
WorkflowTemplateService Manages workflow templates.
intradoc.admin.AdminService Performs functions through the Admin Server. Generally called internally by the Oracle Content Server itself. These services are very complicated, and failing to call them correctly can result in the loss or corruption of Oracle Content Server data. Therefore, it is strongly recommends that you do not use or modify these services.

In the example of the DELETE_DOC service, the service class is DocService:

DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)

3.1.2.2 Access Level

The service security model is similar to the document security model used throughout the Oracle Content Server system. The access level attribute assigns permission levels to the service. Any user attempting to execute the service must have at least this permission.

Security access is stored as bit flags. Generally only one privilege out of READ, WRITE, DELETE, or ADMIN is assigned to a service. The access level number is the sum of the following possible bit flags:

Bit Flag Permission Description
1 READ_PRIVILEGE Read permission is required for the security group referenced in the service.
2 WRITE_PRIVILEGE Write permission is required for the security group referenced in the service.
4 DELETE_PRIVILEGE Delete permission is required for the security group referenced in the service.
8 ADMIN_PRIVILEGE Admin permission is required for the security group referenced in the service.
16 GLOBAL_PRIVILEGE The service calls the global security check to determine if the current user has permission to execute the service. The check validates if the admin role is required or if the user only needs a given permission (Read, Write, or Delete) on at least one security group.
32 SCRIPTABLE_SERVICE Scriptable services don't require parameter input, so they can be called with the executeService function on dynamic server pages.

If a service is acting on a document, the user must have READ, WRITE, DELETE, or ADMIN permission (in that order) for that document's security group to execute the service. For example, to subscribe to a document the user only needs READ permission for that document's security group. However, to check in a new document the user would also need WRITE permission for that document's security group.

If the service does not act on a specific document (such as GET_USER_INFO, CHECKIN_NEW_FORM, and so forth), the GLOBAL_PRIVILEGE bit flag should be set along with at least one more permission bit flag. The user must have that level of permission in at least one security group to execute the service

Note:

A service should never just specify the GLOBAL_PRIVILEGE bit flag alone. At least one more permission bit flag should be specified.

SCRIPTABLE_SERVICE permission means that the service can be executed through the executeService IdocScript function. This should be restricted to read-only services, such as GET_SEARCH_RESULTS, GET_USER_INFO, and so forth.

The following is a complete list of all access levels and their meanings:

  • 0: no access allowed

  • 1: Read permission required

  • 2: Write permission required

  • 3: Read/write permission required

  • 4: Delete permission required

  • 8: Admin permission required

  • 16: Global permission required

  • 17: Global and read permission required

  • 18: Global and write permission required

  • 19: Global and read/write permission required

  • 23: Global, read/write/delete permission required

  • 24: Global, admin permission required

  • 32: Scriptable permission required

  • 33: Scriptable and read permission required

  • 34: Scriptable and write permission required

  • 40: Scriptable and admin permission required

  • 49: Scriptable and global, read permission required

  • 50: Scriptable, global, write permission required

  • 51: Scriptable, global, read/write permission required

  • 56: Scriptable, global, admin permission required

In the example of the DELETE_DOC service, the access level is 4, meaning that the user must have DELETE_PRIVILEGE to execute the service:

DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)

As another example, the access level for the ADD_ALIAS service is 24, meaning that the user must have ADMIN_PRIVILEGE and GLOBAL_PRIVILEGE to execute the service:

ADD_ALIAS UserService 24 null null aliases !csUnableToAddAlias

For details about user accounts and roles permissions see the Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

3.1.2.3 Template Page

The template page attribute specifies the template that displays the results of the service. If the results of the service do not require presentation (such as the PageHandlerService type), this attribute is null.

Templates are a combination of HTML and IdocScript. The IdocScript is used to format the HTML and display the data in the response. The template page name is mapped to an HTM file in the IdcHomeDir/components/Folders/resources/templates/templates.hda file:

  • Most template pages are mapped in the IntradocTemplates ResultSet.

  • Search template pages are mapped in the SearchResultTemplates ResultSet.

In the example of the DELETE_DOC service, the template page that presents the results of the service is MSG_PAGE, which is mapped to the msg_page.htm file:

DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)

3.1.2.4 Service Type

The service type attribute specifies if the service is to be executed as a SubService inside another service. You cannot call a second service from a main service unless the second service is a SubService.

Service Type Description
SubService The service is a subservice that is executed only inside another service.
null The service is not a subservice.

For example, the UPDATE_DOCINFO service executes the UPDATE_DOCINFO_SUB, which has the service type of SubService.

In the example of the DELETE_DOC service, the service is not a subservice, so the service type is null:

DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)

3.1.2.5 Subjects Notified

The subjects notified attribute specifies the subjects (subsystems) to be notified by the service. If a service changes one or more subjects, it must notify the remote sources (such as database tables) that cached information has been updated.

For example, if you do an IsJava=1 call for any service, you will always see changedSubjects and refreshSubjects in the response. These subjects are used to notify the client when the state of the Oracle Content Server instance has changed. For example, they notify the client when a new user is added to the system, when a new document has been checked in, when custom metadata has been changed, and so on. This allows external applications to refresh their data when the Oracle Content Server state changes. It is also the underlying mechanism behind keeping the Oracle Content Server administration applets up-to-date with the number of users, document types, and documents in the system. For example, if you launch the Repository Manager and then check in a new document, you will (in a few seconds) see that item appear in the applet.

The subjects notified string is a comma-delimited list of changed subjects. (If no subjects are notified, this attribute is null.) For example, the value of the subjects notified attribute for the EDIT_METADEF service is metadata,dynamicqueries. This service modifies a metadata field, and subsequently informs the system that the metadata and dynamicqueries subjects have changed.

Possible subjects are:

Subject Must be notified of changes to:
accounts Predefined accounts
aliases User aliases
collections Archiver collections
config Global configuration information
docformats File formats
doctypes Content Types
documents New content items, revised content items, or updated content item metadata
dynamicqueries Dynamic queries that retrieve the list of metadata fields from the database
indexerstatus Indexer status
indexerwork Content items; specifies that an indexing update cycle is required
metadata Metadata fields
metaoptlists Metadata field option lists
pagelist Library (Web Layout Editor) pages
renditions Additional renditions (from XML Converter, Thumbnails, and so forth)
reports Report data sources
schema Schema definitions
searchapi Connection to the indexing search engine
subscriptiontypes Subscription types
templates Search result templates (which are configured from Web Layout Editor)
usermetaoptlists User information field option lists
users User information
wfscripts Workflow event scripts
wftemplates Workflow templates
workflows Workflows

In the example of the DELETE_DOC service, the documents subject is the only subject notified:

DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)

3.1.2.6 Error Message

The error message attribute defines the error message that is 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 Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management.

In the example of the DELETE_DOC service, the error message is a localized string:

DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)

3.1.3 Actions

The Actions column defines one or more steps taken to process the service. An action is an operation to be performed as part of a service script. Actions can execute SQL statements, perform a query, run code, cache the results of a query, or load an option list. The data returned by one action can alter the behavior of later actions.

An action is defined as a list of colon-separated segments, using the following format:

type:name:parameters:control mask:error message

See the following sections for more information:

Figure 3-4 The Actions Column of the DELETE_DOC Service Definition

Surrounding text describes Figure 3-4 .

3.1.3.1 Action Type

The first segment of an action statement defines the type of action.

  • Action Type #: used to identify the action type in the service resource file.

  • Component Wizard Identifier: used to identify the action type in the Component Wizard. In the service resource file, the action type is represented as a number.

  • Java Constant: used to identify the action type in Java code.

The possible action types are:

Action Type # Component Wizard Identifier Java Constant Description
1 Select query QUERY_TYPE Executes a predefined SQL database query to retrieve information (read-only action) and then immediately discards the results. For example, a select query might be used to see if a specific dDocName (Content ID) already exists in the database. The query is specified by the Action Name of the action.
2 Execute query EXECUTE_TYPE Executes a predefined SQL database query to delete, add, or update information in the database.
3 Java method CODE_TYPE Specifies a code module that is a part of the Java class implementing the service.
4 Load option list OPTION_TYPE Loads an option list stored in the system. This is a deprecated action type.
5 Select cache query CACHE_RESULT_TYPE Executes an SQL database query to retrieve information (read-only action) and then stores the results for later use. For example, a select cache query might be used to find all users subscribed to a content item and save the list for display to consumers. The query is specified by the Action Name of the action.

In the example of the first action of the DELETE_DOC service, the action is a Select cache query type (5):

5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExists

3.1.3.2 Action Name

The second segment of an action statement defines the name of the action.

  • For the Java method action type, the action name is the Java method.

  • For the Load option list action type, the action name is the option list.

  • For the Select query, Execute query, and Select cache query action types, the action name is the query name. For standard Oracle Content Server services, typically uses a prefix to identify the action performed on the database. The possible prefixes for queries are:

    Query Prefix Description
    Q Query (retrieve) information from the database (read-only action).
    D Delete information from the database.
    I Insert (add) information in the database.
    U Update information in the database.

In the example of the first action of the DELETE_DOC service, the name of the action is QdocInfo. This specifies that a read-only query (Q) will be performed on the database:

5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExists

3.1.3.3 Action Parameters

The third segment of an action statement specifies the parameters that the action requires. If no parameters are required, this segment is left empty (two colons appear in place of the parameters).

  • If the action requires parameters, enter the parameters as a comma-delimited list.

  • For the Select cache query action type, the first parameter is the name that the action assigns to the ResultSet returned from the query. This ResultSet can then be referenced in the template page.

  • For the Load option list action type, the parameters are optional. However, if parameters are given, the first parameter is the key under which the option list is loaded, and the second parameter is the selected value for display on an HTML page.

In the example of the first action of the DELETE_DOC service, the ResultSet that is returned from the service query will be named DOC_INFO:

5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExists

3.1.3.4 Action Control Mask

The fourth segment of an action statement is an optional bit flag that controls the results of queries to the Oracle Content Server database.

  • Control Mask Bit Flag: Used to identify the control mask in the service resource file. The control mask number used in the service resource file represents the sum of the bit flags for all controls being applied. For standard Oracle Content Server services, the control mask bit flag is typically used instead of the control mask string value.

  • Control Mask String Value: Used to identify the control mask in the service resource file. For multiple control masks, the string values are placed in a comma-delimited list. For custom services, the string value is used instead of the control mask bit flag.

  • Component Wizard Identifier: Used to identify the control mask in the Component Wizard. In the service resource file, the control mask is represented by either the sum of its bit flags (standard Oracle Content Server services), or a comma-delimited list of bit flag string values (custom services).

  • Java Constant: Used to identify the control mask in the Java code.

The possible control masks are:

Control Mask Bit Flag Control Mask String Value Component Wizard Identifier Java Constant Description
0 - - - No control is applied.
1 ignoreError Ignore error CONTROL_IGNORE_ERROR Do not terminate the service on error.
2 mustExist Check result non-empty CONTROL_MUST_EXIST At least one record must be returned by the query, or the action fails. Used only for the Select query and Select cache query action types.
4 beginTran Begin transaction CONTROL_BEGIN_TRAN Starts a database transaction.
8 commitTran Commit transaction CONTROL_COMMIT_TRAN Concludes a database transaction.
16 mustNotExist Check result empty CONTROL_MUST_NOT_EXIST Query must not return any rows, or the action fails. Used only for the Select query and Select cache query action types.
32 retryQuery Retry query CONTROL_RETRY QUERY When the action type is set to Execute query and the query fails, the error will be logged. After three seconds, the query will be run again. If the query fails three times, the service will fail. Used mostly for checking in content. No longer used.
64 doNotLog Do not log CONTROL_DO_NOT_LOG When the action type is set to Select query and the query fails, the service will fail. However, the error will NOT be logged in the system logs. Used internally by when developing components as a debug flag for testing.

Note:

The Check result non-empty and Check result empty control masks are used only for the Select query and Select cache query action types. See Section 3.1.3.1, "Action Type."

In the example of the first action of the DELETE_DOC service, the control mask value is 6, which means that at least one record must be returned by the query (2), and the action starts a database transaction (4):

5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExists

If this was a custom service created using the Component Wizard, the sum of the control mask bit flags would be replaced by a comma-delimited list of the bit flag string values:

5:QdocInfo:DOC_INFO:mustExist, beginTran:!csUnableToDeleteItem(dDocName)
!csRevisionNoLongerExists

3.1.3.5 Action Error Message

The fifth segment of an action statement defines the error message to be displayed if this action fails. This can be either an actual text string or a reference to a locale-sensitive string. For more information, see Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management.

  • An action error message overrides the error message provided as an attribute of the service.

  • If the error message for an action is not null, it becomes the error message for the remainder of the actions in the service.

  • If the error message for an action is null, the error message remains unchanged from the previous action.

  • String references are preceded by an exclamation point.

In the example of the first action of the DELETE_DOC service, the error message is a combination of two localized strings:

5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExists

3.2 Service Example

The DOC_INFO service provides a good example of how services, queries, and templates work together. This section covers the following topics:

3.2.1 DOC_INFO Service Definition

This section shows details of the DOC_INFO service definition from the IdcHomeDir/resources/core/templates/std_services.htm file.

The following is an example of the DOC_INFO service definition, displayed in a text editor:

<@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:DOCINFO,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@>

Figure 3-5 Example of the DOC_INFO Service Definition

Surrounding text describes Figure 3-5 .

3.2.2 DOC_INFO Attributes

The following table describes the attributes of the DOC_INFO service:

Attribute Value Description
Service class DocService This service is providing information about a content item.
Access level 33 1 = The user requesting the service must have Read permission on the content item.

32 = This service can be executed with the executeService Idoc Script function.
Template page DOC_INFO This service uses the DOC_INFO template (doc_info.htm file). The results from the actions will be 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 the error message string:

Unable to retrieve information about the revision

3.2.3 DOC_INFO Actions

The DOC_INFO service executes the following ten actions.

3.2.3.1 Action 1 Definition and Description

Action 1 takes the following form:

  • Action 1 - 5:QdocInfo:DOC_INFO:2:!csItemNoLongerExists2

  • 5 : Select cache 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 a ResultSet called DOC_INFO and stored for later use.

  • 2 : The Check result non-empty control mask specifies that the query must return a record, or the action fails.

  • !csItemNoLongerExists2 : If this action fails on an English Oracle Content Server system, it returns the error message string:

    This content item no longer exists

3.2.3.2 Action 2 Definition and Description

Action 2 takes the following form:

  • Action 2 : 3:mapNamedResultSetValues:DOCINFO,dStatus,dStatus,dDocTitle,dDocTitle:0:null

  • 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.2.3.3 Action 3 Definition and Description

Action 3 takes the following form:

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

  • 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 ResultSet and evaluates the assigned security level to verify that the user is authorized to perform this action.

  • DOC_INFO : ResultSet 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 the error message string:

    Unable to retrieve information for '{dDocName}.'

3.2.3.4 Action 4 Definition and Description

Action 4 takes the following form:

  • Action 4 : 3:getDocFormats:QdocFormats:0:null

  • 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.2.3.5 Action 5 Definition and Description

Action 5 takes the following form:

  • Action 5 : 3:getURLAbsolute::0:null

  • 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.2.3.6 Action 6 Definition and Description

Action 6 takes the following form:

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

  • 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.2.3.7 Action 7 Definition and Description

Action 7 takes the following form:

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

  • 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.2.3.8 Action 8 Definition and Description

Action 8 takes the following form:

  • Action 8 : 3:getWorkflowInfo:WF_INFO:0:null

  • 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, 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.2.3.9 Action 9 Definition and Description

Action 9 takes the following form:

  • Action 9 : 3:getDocSubscriptionInfo:QisSubscribed:0:null

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

3.2.3.10 Action 10 Definition and Description

Action 10 takes the following form:

  • Action 10 :

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

  • 5 : Select cache 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 a ResultSet called REVISION_HISTORY. The DOC_INFO template loops on this ResultSet 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:

    Ubpnable to retrieve revision history for ''{dDocName}.''

3.2.4 DOC_INFO Template

The template page for the DOC_INFO service is the DOC_INFO template. It is important to know what is happening between the files so that you can understand the interactions between the template page and the actions performed in a service.

The definition for the content that the doc_info.htm template contains is located in the IdcHomeDir/components/Folders/resources/std_page.htm file. Code from both files appear in the following markup section:

Markup from the IdcHomeDir/resources/core/templates/doc_info.htm file:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>

<$include std_info_html_head_declarations$>

</head>
<$include info_body_def$>
<$include info_page_content$>
</body>
</html>

Markup from the IdcHomeDir/components/Folders/resources/std_page.htm file that defines what will appear in the doc_info.htm template:

<@dynamichtml info_page_content@>
<$include std_page_begin$>
<$include std_header$>
…
<!-- Do a loop on DOC_INFO so that all substitution tags will use DOC_INFO as 
their first place to find their values.  Otherwise their is confusion between 
this result set and the REVISION_HISTORY table that comes later.  For example 
'dStatus' is a value in both tables-->
<$loop DOC_INFO$>
<$if AllowPrimaryMetaFile and isTrue(AllowPrimaryMetaFile) and
isTrue(dFormat like "*idcmeta*")$>
<$showPrimaryMetaFileFields = "1"$>
<$endif$>
<$include doc_info_notify_data$>

<table border=0 cellpadding=2 cellspacing=0 width=<$docInfoWidth-30$>>
<caption align=top><h4 class=pageTitle><$pageTitle$></caption>
<$include special_checkin_fields1$>
<$include std_revision_label_field$>
<$include std_document_type_field$>
<$include std_document_title_field$>
<$include author_checkin_field$>
<$include std_meta_fields$>
<$include security_checkin_fields$>
<$include checkout_author_info_field$>
<$if IsStagingDoc$>
<$include doc_date_fields$>
<$endif$>
<$fieldName = "dStatus", fieldCaption = "Status"$><$include std_displayonly_field$>
<$if HasOriginal$>
<$fieldName = "dDocFormats", fieldCaption = "Formats"$><$include std_display_field$>
<$endif$>
<$include workflow_list_for_doc$>
<$if HasUrl$>
<$include doc_url_field$>
<$endif$>
<$if HasOriginal and not ClientControlled and not showPrimaryMetaFileFields$>
<$fieldName = "dOriginalName", fieldCaption = "Get Native File"$>
<$if DownloadApplet$>
<$valueStyle="xxsmall", fieldValue = strTrimWs(inc("download_file_by_applet_form_content"))$>
<$else$>
<$fieldValue = strTrimWs(inc("doc_file_get_copy"))$>
<$endif$>
<$if DownloadApplet$><form name=downloadForm><$endif$>
<$include std_displayonly_field$>
<$if DownloadApplet$></form><$endif$>
<$endif$>
<$if IsFailedConversion or IsFailedIndex or IsDocRefinePassthru$>
<$if IsFailedConversion$><$include std_namevalue_separator$><$endif$>
<tr>
<td align=right><span class=errorHighlight>
<$if IsFailedIndex$>Index Error:
<$else$>Conversion Error:
<$endif$></span></td>
<td>
<table>
<tr>
<td><span class=tableEntry>
<$dMessage$>
<$if IsFailedIndex$>
<br>Content has been indexed with Info only.
Resubmit should only be performed if the problem has been resolved.
<$elseif IsDocRefinePassthru$>
<br>Content Refinery failed to convert the content item but released it to the
web by copying the native file.
<$endif$></span></td>
<td><form action="<$HttpCgiPath$>" method="POST">
<input type=hidden name=dID value="<$dID$>">
<input type=hidden name=dDocName value="<$dDocName$>">
<input type=hidden name=IdcService value="RESUBMIT_FOR_CONVERSION">
<input type=submit value= "Resubmit ">
<$if ClientControlled$>
<input type=hidden name=ClientControlled value="DocMan">
<$endif$>
</form></td>
</tr>
</table>
</td>
</tr>
<$if IsFailedConversion$><$include std_namevalue_separator$><$endif$>
<$endif$>
</table>
<$if IsNotSyncRev$>
<table width="100%">
<tr>
<td align=center><span class=errorHighlight>The local copy of this content item has
not been updated to the latest revision.  Use <i>Get Native File</i> or <i>Check out</i>
to update your local copy of <i><$dDocName$></i>.</span></td>
</tr>
</table>
<$endif$>

<$if IsStagingDoc$>
<br>
<table width="90%">
<tr>
<td width="20%" align=center><$include doc_problem_reports$></td>
<td width="20%" align=center><$include project_problem_reports$></td>
</tr>
</table>
<$include doc_provider_info$>
<$else$>
<table width="90%">
<tr>
<$if ClientControlled$>
<td width="20%" align=center><$include doc_select_actions$></td>
<$else$>
<td width="20%" align=center><$include doc_file_undo_checkout$></td>
<td width="20%" align=center><$include doc_file_checkout$></td>
<td width="20%" align=center><$if showPrimaryMetaFileFields$><$include meta_file_update$>
<$else$><$include doc_file_update$><$endif$></td>
<$endif$>
<td width="20%" align=left><$include doc_subscription_unsubscription$></td>
<$if ClientControlled$>
<td width="20%"></td>
<td width="20%"></td>
<$endif$>
</tr>
</table>
<$endif$>
<$if HasOriginal and DownloadApplet$>
<$include download_native_applet$>
<$endif$>

<!-- end loop on DOC_INFO-->
<$endloop$>
<$if IsStagingDoc$>
<!-- present a problem report form -->
<$include doc_add_problem_report$>
<$else$>
<!-- Table holding information about all revisions of this document-->
<$include doc_rev_table$>
<$endif$>
</td>
</tr>
</table>
<$include std_page_end$>
<@end@>

3.3 Creating a Service Resource

There are two ways to create a service resource for use with a custom component:

3.3.1 Creating a Custom Service Manually

To create a custom service resource manually:

3.3.2 Define the service in an HTM file

The HTM file must include a table that is identical in structure to the StandardServices table. See Section 3.1, "Service Structure Overview."

Make a copy of the std_services.htm file, place it in your custom component's /resources directory, and rename the file to avoid confusion. For example:

/custom/my_component/resources/my_services.htm

  1. Change the name of the StandardServices table to a new name. For example:

    <@table MyServices@>

  2. Delete all of the rows in the table except for a service that is similar to the one you want to create.

  3. Edit the entries in the Name, Attributes, and Actions columns.

  4. Save and close the file.

For example, the following HTM file shows two custom services named ADD_REPORT and REPORTS_LIST:

Here is an example of a custom services HTM file, displayed in a text editor.

<HTML>
<HEAD>
<META HTTP-EQUIV='Content-Type' content='text/html; charset=iso-8859-1'>
<TITLE>Custom Scripted Services</TITLE>
</HEAD>
<BODY>
<@table MyServices@>
<table border=1><caption><strong>Scripts For Custom Services
</strong></caption>
<tr>
<td>Name</td><td>Attributes</td><td>Actions</td>
</tr>
<tr>
<td>ADD_REPORT</td>
<td>Service
18
ADD_REPORT_FORM
null
null<br>
Unable to add report.</td>
<td>2:Ireport::0:null</td>
</tr>
<tr>
<td>REPORTS_LIST</td>
<td>Service
17
REPORT_LIST_FORM
null
null<br>
Unable to retrieve reports.</td>
<td>5:Qreports:REPORT_LIST:0:null</td>
</tr>
</table>
<@end@>
<br><br>
</BODY>
</HTML>

Figure 3-6 Example of Custom Services HTM File, Displayed in a Web Browser

Surrounding text describes Figure 3-6 .

3.3.2.1 Load the service in the custom component HDA file

  1. Open the component definition (glue) file of the custom component in a text editor. For example, DomainHome/ucm/cs/custom/my_component/my_component.hda.

  2. Add the new HTM file to the ResourceDefinition ResultSet. For example:

    @ResultSet ResourceDefinition
4
type
filename
tables
loadOrder
service
resources/my_services.htm
MyServices
1
@end

  3. Save the file.

3.3.3 Creating a Custom Service using Component Wizard

To create a service resource using the Component Wizard:

  1. In the Component Wizard, open the component the resource will be created for.

  2. On the Resource Definition tab, click Add.

    The Add Resource screen is displayed.

Figure 3-7 Defining a New Custom Service

Surrounding text describes Figure 3-7 .

  1. Select the Service option.

  2. Enter the file name for the resource file. The default file name is resources/componentname_service.htm.

    If a resource file has been created for services, you can append the new service table to the existing file by selecting the file name. Any changes you make to the load order will apply to the entire resource file.

    To create a new resource file with a different file name, enter the file name. For example, my_services.htm.

  3. If you want the new resource file to be loaded in a particular order, enter the number in the Load Order field.

    Note:

    Unless you have a particular reason for the resource file to be loaded after other resources, you should leave the load order set to 1.

  4. Click Next.

    The Add Service Table Information screen is displayed.

Figure 3-8 Defining a New Service Table

Surrounding text describes Figure 3-8 .

  1. Enter a name for the service table.

    It is a good idea to leave the name of the component as a prefix. For example, My_Component_Services.

    Each service table in a component must have a unique name, even if the tables are in different resource files.

  2. Click Next.

    The Add Service screen is displayed.

Figure 3-9 Defining Service Attributes

Surrounding text describes Figure 3-9 .

  1. Enter the service attributes directly, or start with an existing service definition as follows:

    1. Click Select.

      A list of commonly used services is displayed.

      Select the Show All check box to show the entire list of predefined services.

    2. Select a service from the list. To view details about a service, highlight the service name and click Preview.

      Tip:

      To view the online help for the selected service, click the Help button on the Preview Information for Service <SERVICE_NAME> dialog.

    3. Click OK.

      The service attributes and actions are filled in.

      Note:

      If you do not change the name of the service and this component is loaded last, the custom service will override the standard service and any other custom services with the same name.

    4. Edit the service attributes as necessary.

  2. Enter the actions as necessary.

    • Actions must appear in the Actions list in order of execution. Use the Up and Down buttons to move the selected action.

    • To add an action, click Add. Enter the action definition and click OK.

    • To edit an action, select the action and click Edit. Modify the action definition and click OK.

    • To remove an action, select the action and click Delete.

Figure 3-10 Defining an Action

Surrounding text describes Figure 3-10 .

  1. Click Finish.

    A dialog box asks if you want to launch the text editor to continue editing.

  2. Click Yes to open the resource file in the text editor. Click No to return to the Component Wizard.

    The service resource file now appears in the Custom Resource Definition list, and the service table appears in the Table Name list in the right pane.

Figure 3-11 Custom Service Resource Defined in the Component Wizard

Surrounding text describes Figure 3-11 .