3.1 Service Overview

A service is a function or procedure that is performed by the Content Server. Calling a Content Server service (making a service request) is the only way a client can communicate with the Content Server or access the database.

This section covers the following topics:

"Service Requests and Responses"
"Page Retrieval"
"Content Server Search Services"
"Integration Methods"
"Calling Services Using Persistent URLs"
"Customizing Locale Parameters"

3.1.1 Service Requests and Responses

Any service can be called either externally (from outside the Content Server) or internally (within the Content Server itself). Typically, client services are called externally, while administrative services are called internally. When a service is requested, any applicable parameters are passed to the service. The service uses its attributes and actions to execute the request based on the specified parameters. The service then returns a response either externally or internally, as applicable. This section covers the following topics:

"Internal Service Requests"
"External Service Requests"
"Request Parameters"
"Date and Time Formatting"
"Case Sensitivity Considerations"

3.1.1.1 Internal Service Requests

Although any service can be called internally, typically only administrative services are called internally. Internal service requests are made from within the Content Server itself, and results are returned only to the Content Server. For example, you can use the START_SEARCH_INDEX service to update or rebuild the search index automatically in a background thread.

3.1.1.2 External Service Requests

Any external program or HTML page can call any Content Server service to request information from the Content Server or perform a specified function, such as full-text and metadata searching, library services, workflow services, subscription notifications, and content conversion capabilities. Typically, only client services are called externally (administrative services are typically called internally). For example, when you click a Search link on a 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

External requests are sent from a client (for example, a Web browser) to the Web server using one of many protocols. The service call must include any parameters that the service requires. The Web server routes the service request to the Content Server, along with any required and optional parameters. The Content Server then executes the service using the provided parameters. In the case of search services, this involves sending a search request to the search engine. The Content Server then returns the results to the Web server, and the Web server returns the results to the Web browser client.

Figure 3-1 External Requests and Responses Between Content Management System Elements

This figure is described in the preceeding text.

3.1.1.3 Request Parameters

A service request must include every parameter that the service requires. For example, when calling the DOC_INFO service to obtain information about a content item, the service call must provide the dID (generated content item revision identifier) to the service. The following segment shows how this would be done through a persistent URL:

http://cs.company.com/cs/idcplg?
IdcService=DOC_INFO&dID=194

3.1.1.4 Date and Time Formatting

Default date and time formatting are determined using the Localization tab on the System Properties. The general format for date and time is:

MM/DD/{yy} {hh:mm[:ss] {aa} [zzz]} !mAM,PM!zTimezoneCity

The date/time format is a grouping of Y, D, M for Year, Day, and Month, and h, m, and s for hours, minutes, and seconds. The number of times the letter repeats designates the minimum number of digits used (for example, YY/MM/DD hh:mm could designate 04/12/09 12:12 or MM/DD/YYYY hh:mm:ss would be 09/12/2004 04:12:33).
The a represents the meridian symbol (for example, AM or PM).
The m represents minutes.
Braces ({ }) indicate that the item is optional when in the input data, but will always appear in the output.
The exclamation mark (!) is used to separate additional date format specifications. For example, !mXXX,YYY could designate the meridian symbols (where XXX is the symbol meaning "before noon" and YYY is the symbol meaning "after noon"). Everything after the exclamation point passes the meridian and time zone symbols along with the date format.

3.1.1.5 Case Sensitivity Considerations

Case sensitivity is important when calling standard Content Server services.

Parameters: Parameters are case sensitive. For example, when specifying the IdcService parameter you must use IdcService, not IDCSERVICE.
Parameter values: Parameter values are typically case sensitive. The value for the IdcService parameter is always case sensitive, and the convention used for standard Content Server services is all capital letters. For example, when specifying the value for the IdcService parameter you must use DOC_INFO, not Doc_Info.
Databases: The database you are using with Content Server might affect the case sensitivity of parameters and parameter values. For example, some databases do not have case-sensitive column names and other databases are case-insensitive by default. So a database may have stored "DDOCNAME", but the value that Content Server expects is still "dDocName". Also, some databases store values in uppercase, but they perform case-insensitive queries. For example, if you store the dDocName "BouncyCaps", a query for "bouncycaps" would find that row.

3.1.2 Page Retrieval

When a Web page is requested from the Content Server, one of the following page types is returned:

static page: The content of a static Web page is pre-formatted, and does not change from one request to the next. In a typical Content Server Web site, the only static page is the guest home page (DomainHome/ucm/cs/weblayout/portal.htm).
dynamic page: A dynamic Web page is assembled at the time of the Web server request, using Content Server services and templates to determine the content and formatting. For example, each user's portal design page is generated using a Content Server service called GET_PORTAL_PAGE and a template called PNE_PORTAL_DESIGN_PAGE.

3.1.3 Content Server Search Services

A search request is a special kind of Content Server service. When the Content Server receives a search request, it sends the request on to the search engine using a search engine API. This allows different search engines to be used with the Content Server.

3.1.4 Integration Methods

Service requests can be made by any external program or HTML page using a wide variety of protocols. Content Server can be integrated with other enterprise applications using a wide variety of integration methods. One common integration method is to reference content that is managed within the Content Server by persistent URL. For more information, see Section 3.1.5, "Calling Services Using Persistent URLs".

The following are other possible integration methods:

Oracle Weblogic Server Web Services (WS) using integrated Weblogic JAXP and SAML support.
Oracle UCM Web services component for the Content Server and Remote Intradoc Client (RIDC) component for clients.
Java API (IdcCommand) integration using the IdcCommand Java Command Utility
Java Server Page (JSP) integration from a JSP running in Content Server, a JSP through the Content Server JavaBean, or a JSP through the Content Server Enterprise JavaBean (EJB) deployed on your J2EE application server
Java 2 Enterprise Edition API (J2EE) integration by deploying the Content Server Enterprise JavaBean on your J2EE-compliant application server
Simple Object Access Protocol (SOAP) integration using the SOAP protocol
Virtual Folders integration using the Folders component
Web Distributed Authoring and Versioning (WebDAV) integration using the WebDAV component
Component Object Model (COM) integration using the ActiveX utility or the IntradocClient OCX component

Note:

For more detailed information on available integration methods, see the Oracle Fusion Middleware Developer's Guide for Content Server.

3.1.5 Calling Services Using Persistent URLs

In this integration method, all of the necessary information for the service call is sent to the Content Server through the URL. The following is a typical URL; in this case, it is the URL for the Home page:

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

http://cs.company.com/ is the Web address of the Content Server instance.
cs/idcplg is the path to the Web server filter.
IdcService=GET_DOC_PAGE tells the Content Server to execute the GET_DOC_PAGE service.
Action=GetTemplatePage tells the Content Server to return the results using a specified template page. This parameter is specific to the GET_DOC_PAGE service example.
Page=HOME_PAGE tells the Content Server which template page to use. This parameter is specific to the GET_DOC_PAGE service example.
The question mark (?) indicates the end of the Web server path and the beginning of Content Server parameters.
Ampersands (&) are used as separators between Content Server parameters.
You can include certain Idoc Script variables in a URL to affect page display at the time of the page request. This is useful for troubleshooting or for customizing your Content Server pages. For example:

Troubleshooting Examples

IsJava=1
IsPageDebug=1

Customization Examples

StdPageWidth=1000
dDocType=HRForm

Example

The following example describes the steps that occur when a persistent URL is used to request a dynamic page from the Content Server.

When a user clicks the Administration link in the navigation area, a request for the GET_ADMIN_PAGE service is sent to the Web server. The URL of the Administration link contains the following commands:
```
IdcService=GET_ADMIN_PAGE&Action=GetTemplatePage&Page=ADMIN_LINKS
```
The Web server recognizes this request as a Content Server function and sends the specific request to the Content Server.
When the Content Server has processed the request, it passes the result back to the Web server. In the case of the Administration link, the GET_ADMIN_PAGE service:
- Provides a login prompt if the user is not currently logged in.
- Verifies that the user has admin permission.
- Assembles the Administration page using the ADMIN_LINKS template.
- Returns the assembled Web page to the Web server.
The Web server delivers the results of the Content Server service to the originating Web browser client.

Example

The following example describes the steps that occur when a persistent URL is used to perform a search request.

When a user clicks the Search button on the standard Search page, a request for the GET_SEARCH_RESULTS service is sent to the Web server. The URL for the search request specifies the service to execute, the search criteria, and the result parameters:
```
IdcService=GET_SEARCH_RESULTS&QueryText=stellent&ftx=1
&AdvSearch=True&ResultCount=25&SortField=dInDate&SortOrder=Desc
```
The Web server recognizes the request as a Content Server function, and sends the specific request to the Content Server.
The Content Server passes the request to the search engine.
The search engine returns the search results to the Content Server.
Based on the user login and security permissions, the Content Server assembles the search results page and returns it to the Web server.
The Web server delivers the results to the originating Web browser client.

3.1.6 Customizing Locale Parameters

When using the Content Server in a client server operation mode, you can use several parameters to improve the handling of locale-sensitive data, helping to avoid date and encoding incompatibility problems.

In the following descriptions, it is assumed that an HDA formatted request is being made to the Content Server using an operation such as IdcClient, IdcCommandUX, IdcServerBean, or a custom server communication.

The following parameters are available:

UserDateFormat: Specifies the date/time format for dates in the incoming request and any dates produced in the response to the request. If not specified, the response format always uses the login user's date locale. If that is unavailable, it uses the Content Server system locale date. Do not use the ODBC date/time format used internally by the Content Server for archiver batch load files; that can create time zone ambiguity errors.
```
UserDateFormat=M/D/YYYY hh:mm[:ss]{aa}!mAM,PM!zUTC
```
blDateFormat: Specifies the format of dates in the body of the incoming request. It does not affect the format of the response. If set, this overrides values set with UserDateFormat. If not specified, the incoming request format uses the login user's locale date format. If that is unavailable, it uses the Content Server system locale date format. This parameter is not available except if one of the headers that precedes the request is a REQUEST_METHOD header with a POST value. GET style requests do not support this parameter.
ClientEncoding: Specifies the character encoding to be used in the response. If no HDA header line exists with either the charset or jcharset specification, this parameter also dictates the encoding used to decode the body of the request.
```
ClientEncoding=cp1252
```
HEADER_ENCODING: Used in the header that precedes the body of the HDA request. This allows the requesting agent to specify the encoding of headers. This functionality is useful for dictating the encoding of the HTTP_INTERNETUSER and REMOTE_USER header entities.
blFieldTypes: Specifies a field type (date or message) during the translation of a response. A 'message' is a formatted string, usually an error message, that has not been localized. You can use this parameter to ensure that ODBC formatted fields are parsed and returned in the format specified by blDateFormat or UserDateFormat and will be applied even if the field is only in the response and not in the request. If the field types are not specified in biFieldTypes, then fields are treated like plain strings and no localization is performed on them.

The only fields that typically need such translation are ones created by customized extensions of Content Server behavior (such as those created using Idoc Script, for example). This is only available for POST style requests (REQUEST_METHOD header with value POST). This is normally used to specify additional date fields and is best used in combination with UserDateFormat or blDateFormat to indicate that a field needs special handling as a date.
```
blFieldTypes=xNewDate date, xComment message
```
extraFieldTypes: Specifies a field type during the translation of a response to HDA formatted requests, used in place of blFieldTypes. It is best used inside an Idoc script expression that is executed when fulfilling a Content Server request. It cannot be used in Idoc script when generating the format of the response because the response is in a data format (such as HDA). It can, however, be used in other places where Idoc script is evaluated when executing the logic of a request, such as the processing of an HCSP form, or determining the effects of a document profile.
```
extraFieldTypes=xNewDate date, xComment message
```
convertDatabaseDate: Ensures that blFieldTypes or extraFieldTypes are used to convert the ODBC date format to the desired response date format. This variable is necessary when using the blFieldTypes or extraFieldTypes variables.

If this variable is not set, the ODBC date formats may not be converted to the desired response date format. ODBC dates can still be converted even if this variable is not set. This occurs if the Content Server determines that the response needs a full coercion from one date format to another. This typically happens only if the incoming date format is different from the outgoing date format.
```
convertDatabaseDate=1
```
SuppressResultLocalization: Suppresses localization conversions performed before the response is sent back. Conversions done on incoming data can still be performed.

This parameter is useful to prevent messages from being localized or dates being fully converted. An example of usage is when the response is to be forwarded to another Content Server to be processed or when the data is to be persistently stored and replayed back to the original Content Server as needed.
```
SuppressResultLocalization=1
```
All of the parameters that affect date and message processing can be used with this parameter, but the other parameters are only used when the data is replayed against another Content Server or the current Content Server.

Note:

The operation making the HDA request may set values for these parameters; therefore, users may find that the values they set do not change the behavior as expected.

3.1.7 Forcing Authentication Challenges

It is sometimes necessary that a user be re-authenticated for a Content Server service or for other activities. For example, during a workflow, it might be necessary to acquire a 'digital signature' for a user at a specific step in the workflow process. This can be done using the isRepromptLogin configuration variable. See the Oracle Fusion Middleware Idoc Script Reference Guide for details about its usage.

To force re-authentication of any service, perform the following steps:

Add checkForRevalidateLogin as a service definition function.
Add revalidateLoginID as a parameter to the service call being made, with a randomly generated value.

These two actions cause the Content Server to refuse to accept the currently supplied credentials until the AllowedLoginID cookie is set with the same value as the parameter to revalidateLoginID. The cookie is set during the redundant challenge to the current credentials.

Note that this clears the current credentials so the user will need to login again to access any Content Server functionality.