| Oracle® Fusion Middleware Services Reference Guide for Oracle Universal Content Management 11g Release 1 (11.1.1) E11011-01 |
|
 Previous |
 Next |
Home > Services Reference Guide fo... > Customizing Services > Service Structure Overview
| Oracle® Fusion Middleware Services Reference Guide for Oracle Universal Content Management 11g Release 1 (11.1.1) E11011-01 |
|
Previous |
Next |
Home > Services Reference Guide fo... > Customizing Services > Service Structure Overview
This section describes how standard services are implemented in Content Server. For information about calling services from other programs, see the chapter about integration methods in the Oracle Fusion Middleware Developer's Guide for Content Server.
A service resource is defined in an HTM file using a ResultSet table with the following three columns:
The standard 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 result set.
The following table row is an example of a service definition:
The Name column 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 Content Server Web page.
The Attributes column defines aspects of each service, discussed in the following sections:
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 Content Server. |
| IndexerService | Performs functions related to indexing for search engine maintenance. |
| ListBoxService | Downloads lists from the 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 Content Server itself. These services are very complicated, and failing to call them correctly can result in the loss or corruption of 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)
The service security model is similar to the document security model used throughout Content Server. 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 Content Server.
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)
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)
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 Content Server 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 Content Server state changes. It is also the underlying mechanism behind keeping the 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 |
| projects | Registered Content Publisher projects |
| 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)
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 Getting Started with the Software Developer's Kit (SDK).
In the example of the DELETE_DOC service, the error message is a localized string:
DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
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:
|
Note: In an HTM resource file that defines services, 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 list of actions, without a line break in between. |
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
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 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
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
The fourth segment of an action statement is an optional bit flag that controls the results of queries to the 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 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 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 "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
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 Getting Started with the Software Developer's Kit (SDK).
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
