2 Using Services

This chapter discusses how to use Oracle WebCenter Content services and provides an example of a custom service.

This chapters covers the following topics:

2.1 Overview of Services

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

This section covers the following topics:

2.1.1 Service Requests and Responses

Any service can be called either externally (from outside the Oracle WebCenter Content system) or internally (within the Oracle WebCenter Content system 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:

2.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 Oracle WebCenter Content itself, and results are returned only to Oracle WebCenter Content. For example, you can use the START_SEARCH_INDEX service to update or rebuild the search index automatically in a background thread.

2.1.1.2 External Service Requests

Any external program or HTML page can call any Oracle WebCenter Content service to request information from the Oracle WebCenter Content system 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 Oracle WebCenter Content system, along with any required and optional parameters. The Oracle WebCenter Content system 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 Oracle WebCenter Content system then returns the results to the Web server, and the Web server returns the results to the web browser client.

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

Description of Figure 2-1 follows
Description of "Figure 2-1 External Requests and Responses Between Content Management System Elements"

2.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.example.com/cs/idcplg?
IdcService=DOC_INFO&dID=194

2.1.1.4 Date and Time Formatting

Default date and time formatting for Content Server are determined using the Localization tab on the System Properties utility interface. 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.

  • The m indicates that it will be parsed if present but won't be in the output when used for formatting.

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

2.1.1.5 Case Sensitivity Considerations

Case sensitivity is important when calling standard Oracle WebCenter Content 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 Oracle WebCenter Content 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 Oracle WebCenter Content 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 the Oracle WebCenter Content system 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.

2.1.2 Page Retrieval

When a web page is requested from the Oracle WebCenter Content system, 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 Oracle WebCenter Content web site, the only static page is the guest home page (for example, DomainHome/ucm/cs/weblayout/portal.htm).

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

2.1.3 Search Services

A search request is a special kind of Oracle WebCenter Content service. When the Oracle WebCenter Content system 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 Oracle WebCenter Content system.

2.1.4 Integration Methods

Service requests can be made by any external program or HTML page using a wide variety of protocols. The Oracle WebCenter Content system 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 Oracle WebCenter Content system by persistent URL. For more information, see 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 WebCenter Content 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 Oracle WebCenter Content, a JSP through the Oracle WebCenter Content JavaBean, or a JSP through the Oracle WebCenter Content Enterprise JavaBean (EJB) deployed on your J2EE application server

  • Java 2 Enterprise Edition API (J2EE) integration by deploying the Oracle WebCenter Content Enterprise JavaBean on your J2EE-compliant application server

  • Common Object Request Broker Architecture (CORBA) integration by implementing Remote Method Invocation (RMI) over Internet Inter-ORB Protocol (IIOP) as the transport protocol and referencing the Enterprise JavaBean

  • Open Document Management API (ODMA) integration using the ODMA-based plug-in. (Deprecated in 11g)

  • Simple Object Access Protocol (SOAP) integration using the SOAP protocol

  • Virtual Folders integration using the Folders_g 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

2.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 example shows a typical URL; in this case, it is the URL for the Home page:

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

  • http://cs.example.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.

Troubleshooting Examples

  • IsJava=1

  • ScriptDebugTrace=1

  • IsPageDebug=1

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

  1. When a user clicks the Administration link in the navigation area, a request for the GET_ADMIN_PAGE service is sent to the Web server. The URL of the Administration link contains the following commands:

    IdcService=GET_ADMIN_PAGE&Action=GetTemplatePage&Page=ADMIN_LINKS

  2. The Web server recognizes this request as a Content Server function and sends the specific request to the Content Server.

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

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

  1. When a user clicks the Search button on the standard Search page, a request for the GET_SEARCH_RESULTS service is sent to the Web server. The URL for the search request specifies the service to execute, the search criteria, and the result parameters:

    IdcService=GET_SEARCH_RESULTS&QueryText=oracle&ftx=1
&AdvSearch=True&ResultCount=25&SortField=dInDate&SortOrder=Desc

  2. The Web server recognizes the request as a Content Server function, and sends the specific request to the Content Server.

  3. Content Server passes the request to the search engine.

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

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

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

2.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 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 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 instance to be processed or when the data is to be persistently stored and replayed back to the original Content Server instance 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 instance or the current Content Server instance.

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.

2.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. For more details on this variable, see isRepromptLogin in Configuration Reference for Oracle WebCenter Content.

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

  1. Add checkForRevalidateLogin as a service definition function.

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

2.2 Custom Application Example

This example application calls five services and defines six private functions.

2.2.1 Services Called

These services are called and a serialized HDA string is built for each:

  • CHECKOUT_BY_NAME

  • CHECKIN_UNIVERSAL

  • DOC_INFO

  • GET_FILE

These parameters for CHECKIN_UNIVERSAL are defined:

  • doFileCopy

  • dDocName

  • dDocTitle

  • dDocType

  • dSecurityGroup

  • dDocAuthor

  • dDocAccount

  • primaryFile

The GET_TABLE service is called and this parameter is defined:

  • tableName

2.2.2 Private Functions

These private functions are defined:

  • getNativeFilePath

  • checkOutByName

  • checkinUniversal

  • getDocInfo

  • getFile

  • parseResultSet

2.2.3 Sample Code

This sample is in Visual Basic.

' Defines a private function.
Private Function getNativeFilePath() As String
Dim idccmd As IdcCommandX
Dim str As String
Dim res
Dim dID As String, dExtension As String, dDocType As String, dDocAccount As String

dID = "2"
dExtension = "pdf"
dDocType = "acc"
dDocAccount = ""

' Builds a serialized HDA string.
str = "@Properties LocalData" + vbCrLf
str = str + "dID=" + dID + vbCrLf
str = str + "dExtension=" + dExtension + vbCrLf
str = str + "dDocType=" + dDocType + vbCrLf
str = str + "dDocAccount=" + dDocAccount + vbCrLf
str = str + "@end" + vbCrLf

Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\oracle\bin")
res = idccmd.computeNativeFilePath(str)

Open "c:\newdoc.txt" For Binary Access Write As #1
Put #1, , str
Put #1, , res
Close #1
MsgBox (res)
End Function

' Defines a private function.
Private Function checkOutByName(ByVal dDocName As String) As String
Dim idccmd As IdcCommandX
Dim idcService As String, str As String
Dim res

' Calls a service and builds a serialized HDA string.
idcService = "CHECKOUT_BY_NAME"
str = "@Properties LocalData" + vbCrLf
str = str + "IdcService=" + idcService + vbCrLf
str = str + "dDocName=" + dDocName + vbCrLf
str = str + "@end" + vbCrLf

' In an actual application the return codes need to be handled. For this example,
' the service is called while there is no content with that specific dDocName.
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\oracle\bin")
res = idccmd.executeCommand(str)
End Function

' Defines a private function.
Private Function checkinUniversal(ByVal doFileCopy As String, ByVal dDocName As
String, ByVal dDocTitle As String, ByVal dDocType As String, ByVal dSecurityGroup
As String, ByVal dDocAuthor As String, ByVal dDocAccount As String, ByVal
primaryFile As String) As String

' Builds a serialized HDA string.
Dim idccmd As IdcCommandX
Dim idcService, res, str As String

' Calls a service and builds a serialized HDA string.
idcService = "CHECKIN_UNIVERSAL"
str = "@Properties LocalData" + vbCrLf
str = str + "IdcService=" + idcService + vbCrLf
str = str + "doFileCopy=" + doFileCopy + vbCrLf
str = str + "dDocName=" + dDocName + vbCrLf
str = str + "dDocTitle=" + dDocTitle + vbCrLf
str = str + "dDocType=" + dDocType + vbCrLf
str = str + "dSecurityGroup=" + dSecurityGroup + vbCrLf
str = str + "dDocAuthor=" + dDocAuthor + vbCrLf
str = str + "dDocAccount=" + dDocAccount + vbCrLf
str = str + "primaryFile=" + primaryFile + vbCrLf
str = str + "@end" + vbCrLf

' exec hda...
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\oracle\bin")
res = idccmd.executeCommand(str)
MsgBox (CStr(res))
End Function

' Defines a private function.
Private Function getDocInfo(ByVal dID As String) As String
Dim idccmd As IdcCommandX
Dim idcService As String, str As String
Dim res

' Calls a service and builds a serialized HDA string.
idcService = "DOC_INFO"
str = "@Properties LocalData" + vbCrLf
str = str + "IdcService=" + idcService + vbCrLf
str = str + "dID=" + dID + vbCrLf
str = str + "@end" + vbCrLf

' exec hda....
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\oracle\bin")
res = idccmd.executeCommand(str)
MsgBox (res)
End Function

' Defines a private function.
Private Function getFile(ByVal dID As String, ByVal dDocName As String, ByVal
RevisionSelectionMethod As String, ByVal Rendition As String)
Dim idccmd As IdcCommandX
Dim idcService, str As String

Dim res As Variant
Dim fileName As String
Dim fileSize As Long
Dim indexStop As Integer

' Calls a service and builds a serialized HDA string.
idcService = "GET_FILE"
str = "@Properties LocalData" + vbCrLf
str = str + "IdcService=" + idcService + vbCrLf
str = str + "dDocName=" + dDocName + vbCrLf
str = str + "dID=" + dID + vbCrLf
If (RevisionSelectionMethod = "Specific" Or RevisionSelectionMethod = "Latest" 
Or RevisionSelectionMethod = "LatestReleased") Then

' Ignore dDocName and use dID instead.
str = str + "RevisionSelectionMethod=" + RevisionSelectionMethod + vbCrLf
End If
If (Revision = "Primary" Or Revision = "Web" Or Revision = "Alternate") Then
str = str + "Revision=" + Revision + vbCrLf
End If
str = str + "@end" + vbCrLf

' exec hda...
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\oracle\bin")
res = idccmd.executeCommand(str)

Open "c:\newdoc.txt" For Binary Access Write As #1
Put #1, , res
Close #1
MsgBox (Len(res))

' chop at filename= and store fileName
indexStop = InStr(res, "filename=")
tmpStr = (Mid(res, indexStop))
indexStop = InStr(tmpStr, Chr(13))
fileName = Mid(tmpStr, 10, indexStop - 10)
MsgBox (fileName)
' MsgBox (CStr(Asc(Mid(tmpStr, 2, 1))))

' chop at Content-length: and store fileSize
tmpStr = Mid(tmpStr, indexStop)
indexStop = InStr(tmpStr, "Content-Length: ")
tmpStr = (Mid(tmpStr, indexStop))
indexStop = InStr(tmpStr, Chr(10))
fileSize = CLng(Mid(tmpStr, 17, indexStop - 17))
MsgBox (CStr(fileSize))
MsgBox (Len(res))
End Function

Private Sub cmdAddUser_Click()
frmAddUser.Show
End Sub

Private Sub cmdCheckin_Click()
Dim idcService As String, doFileCopy As String, dDocName As String
Dim dDocTitle As String, dDocType As String, dSecurityGroup As String
Dim dDocAuthor As String, dDocAccount As String, primayFile As String

' Calls a service and defined parameters.
idcService = "CHECKIN_UNIVERSAL"
doFileCopy = "1"
dDocName = "myDocNameNewh"
dDocTitle = "myDocTitleb"
dDocType = "ADACCT"
dSecurityGroup = "Public"
dDocAuthor = "Jennifer"
dDocAccount = ""
primaryFile = "c:/junk_b.doc"

' In an actual application check for errors.
' Lock the file in order to upload a new revision.
Call checkOutByName(CStr(dDocName))
' If the dDocName is not in the system, it gets added as first revision
' by the CHECKIN_UNIVERSAL call.
Call checkinUniversal(doFileCopy, dDocName, dDocTitle, dDocType, dSecurityGroup, 
dDocAuthor, dDocAccount, primaryFile)
End Sub

Private Sub cmdDocInfo_Click()
Call getDocInfo("269")
End Sub

Private Sub cmdDownload_Click()
Call ba
End Sub

Private Sub cmdGetFile_Click()
Call getFile("14", "", "", "")
End Sub

Private Sub cmdGetNativeFile_Click()
Call getNativeFilePath
End Sub

Private Sub Command1_Click()
Dim idccmd As IdcCommandX
Dim res, str
Open "c:\adduser.txt" For Append As #1
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\oracle\bin")
str = "@Properties LocalData" + vbCrLf + "IdcService=ADD_USER" + vbCrLf +
"dName=Jennifer" + vbCrLf + "dFullName=Jennifer Smith" + vbCrLf +
"dPassword=password" + vbCrLf + "dEmail=email@example.com" + vbCrLf +
"dUserAuthType=LOCAL" + vbCrLf + "@end" + vbCrLf + "@ResultSet UserAttribInfo" +
vbCrLf + "2" + vbCrLf + "dUserName" + vbCrLf + "AttributeInfo" + vbCrLf +
"Jennifer" + vbCrLf + "role,admin,15" + vbCrLf + "@end" + vbCrLf
res = idccmd.executeCommand(str)
Print #1, res
Close #1
End Sub

Private Sub Command2_Click()
Dim idccmd As IdcCommandX
Dim res, str

Dim myRS As String
Dim idcService, tableName As String

idcService = "GET_TABLE"
tableName = "Accounts"

Open "c:\a_getsec.txt" For Append As #1
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\oracle\bin")
str = "@Properties LocalData" + vbCrLf + "IdcService=" + idcService + vbCrLf +
"tableName=" + tableName + vbCrLf + "@end" + vbCrLf
myRS = idccmd.executeCommand(str)

' Parse out the results set.
Call parseResultSet(myRS, tableName)
Print #1, res
Close #1
End Sub

' Calls a private function.
Private Function parseResultSet(strResultsSet As String, strSearchString As
String) As String
Dim indexStop As Integer
Dim tmpStr As String

Dim numberOfRows As Integer
Dim numberOfElementsInSet As Integer
Dim resultElement()
MsgBox (strResultsSet)

' Start of results set.
indexStop = InStr(strResultsSet, "@ResultSet " & strSearchString)

' Check for error (0 index) before moving on.
tmpStr = (Mid(strResultsSet, indexStop))
MsgBox (tmpStr)

' Determine how many data lines are in the HTA file.
indexStop = InStr(tmpStr, "@end")
For i = 1 To indexStop
If (Mid(tmpStr, i, 1) = Chr(10)) Then
numberOfRows = numberOfRows + 1
End If
Next i
numberOfRows = numberOfRows - 2 ' Remove the first line of data.

' Find first line that identifies the ResultsSet
indexStop = InStr(tmpStr, Chr(10))
tmpStr = (Mid(tmpStr, indexStop + 1))

' Get number of elements in record set, chop the line off the record set...
indexStop = InStr(tmpStr, Chr(10))
numberOfElementsInSet = CInt((Mid(tmpStr, 1, indexStop)))
tmpStr = (Mid(tmpStr, indexStop + 1))

' Set storage array.
ReDim resultElement((numberOfRows / numberOfElementsInSet), numberOfElementsInSet)
Dim junk As String
' Populate array from HTA dataset
For i = 1 To (numberOfRows / numberOfElementsInSet)
For j = 1 To numberOfElementsInSet
indexStop = InStr(tmpStr, Chr(10))
resultElement(i, j) = Mid(tmpStr, 1, indexStop - 1)
tmpStr = (Mid(tmpStr, indexStop + 1))
junk = junk + resultElement(i, j)
Next j
Next i
MsgBox (junk)
parseResultSet = "je"
End Function

' Set storage array.
Sub ba()
Dim b() As Byte 'This byte array will capture the file
Dim strURL As String ' URL string
Dim strDest As String ' Destination File

' Set the strURL to a valid address.
'strURL = "http://localhost/cs/idcplg?IdcService=GET_FILE&dID=14"
'strDest = "C:\myjunk.html"
strURL = "localhost"
b() = Inet1.OpenURL(strURL, icByteArray)
'Open strDest For Binary Access Write As #1
'Put #1, , b()
'Close #1
End Sub

2.3 Redirecting Template Page for Response Output

Sometimes it is desirable to display a page other than the default (change the delivery mechanism for the response template) after executing a CGI request (either a GET or a POST). For example, you might want to redirect the page after a login or after executing a search. One way to do this is by modifying the service call through the component architecture, and specifying a different template page. Another more flexible way to do this as needed is to specify the urlTemplate parameter, to redirect the response page to a HCSP or HCST, and reformat the results in any way you want.

This section covers the following topics:

2.3.1 Basic Concepts

You should be somewhat familiar with Idoc Script and with Dynamic Server Pages (HCST, HCSP, HCSF) before attempting this exercise. You should also be somewhat familiar with Content Server feature and component architecture. It would also be helpful to be familiar with HTML FORM objects. For more information see Configuration Reference for Oracle WebCenter Content.

2.3.2 Creating a HCST Page

As an example, we will create a HCST page that can be used as a URL template to reformat the search results. We could also create a HCSP, but for simplicity, we will use a HCST. We will name the file test_result.hcst, and have it contain the following text:

<html>
<table width=300>
<tr bgcolor="#000000" style="color: #ffffff;">
<td><b>Name</b></td>
<td><b>Title (Author)</b></td>
</tr>
<$loop SearchResults$>
<tr <$if doShade$>bgcolor="#E5E7D4"<$endif$>>
<td><a href="<$URL$>"><$dDocName$></a></td>
<td><$dDocTitle$> (<$dDocAuthor$>)</td>
</tr>
<$if doShade$><$doShade=""$><$else$><$doShade="1"$><$endif$>
<$endloop$>
</table>
</html>

Next, we should check this file into the Content Server instance. For simplicity, we will check it into the Public security group, with a content type of ADACCT, and the Content ID test_result. Its URL will then be something like this:

http://myhost/oracle/groups/public/documents/document/test_result.hcst

2.3.3 Reformatting the Search Results Page

To test our new template, we will start by going to a search page. Enter in any search criteria and click Search. You should see the standard search page with your results contained in it.

Now, add this text to the end of the URL that brought you to the search results page:

&urlTemplate=/oracle/groups/public/documents/adacct/test_result.hcst

You should now see the same search results formatted in a minimalist HTML page. Note how the full URL is not used, but just the URL relative to your host computer.

If you would like the default search page to always format pages with this template, you can change the HTML FORM object on the search page to also have this field:

<input type=hidden name='urlTemplate'
value='/oracle/groups/public/documents/document/test_result.hcst'>

This can be done by creating a component that modifies the include query_results_options to contain the sample HTML. Alternatively, the value for urlTemplate can be calculated dynamically on the search page with JavaScript, to redirect to different pages based on the metadata entered by the user.

2.3.4 Additional Options

In addition to urlTemplate, you can also use the parameters docTemplateName, docTemplateID, or RedirectUrl to change the result page. These all have different behavior, as follows:

  • urlTemplate: Set to the full relative URL of the hcst page you want to use. For example:

    IdcService=DOC_INFO&urlTemplate=/idc1/groups/public/documents/adacct/test_result.hcst

    Because RedirectURL doesn't work with all service calls, and pre-6.0 versions of Content Server software have minor data pollution bugs with docTemplateName and docTemplateID, it is usually safest to use urlTemplate. However, if you change the Content Type or the Security Group of your template, then the URL will no longer be valid and will need to be updated. Also, this parameter is not recommended for overriding the template used for a 'POST' service.

  • docTemplateName: Set to a dDocName of a template (for example, test_result). This parameter behaves like urlTemplate, but finds the location of the latest released web-viewable for a document with dDocName of docTemplateName.

  • docTemplateID: Set to a dID of a specific revision of a template (for example, 100). Like docTemplateName, but finds the Web-viewable of a specific dID revision.

  • RedirectUrl: Set to the last part of a CGI URL back into the Content Server (for example, IdcService=DOC_INFO&dID=<$dID$>). This is only for the few dozen 'POST' services that execute the action prepareRedirect, such as CHECKIN_NEW and SUBMIT_HTML_FORM.

  • By using a redirect after each HTML 'POST', the response page can be safely refreshed by the end user without reissuing the post. In the definition of each of these services there is a 3:prepareRedirect:….:0:null line. The RedirectUrl overrides the results of the prepareRedirect method and allows a different URL to be used as the location for redirects. The RedirectUrl can have Idoc Script in it that will be executed just before the redirect is issued. This can create complex Idoc Script nesting, because the RediretUrl assignment will typically occur in a resource includes. For example:

    … Standard Idoc form beginning …
<input type=edit name=myparam value=''>
<input type=hidden name=RedirectUrl
value='<$HttpCgiPath$>?<$xml('IdcService=MY_RESPONSE_TEMPLATE&dID=<$dID$>&
myparam=<$myparam$>')$>'>
… Standard Idoc form closure …

Much of the Idoc Script is nested inside an Idoc literal string. This delays the execution of the script until the redirect URL is being computed. That allows the RedirectUrl to pick up the value of myparam even though the user has still to select its value.

A single quote is used on the outside and a double quote on the inside. This reduces confusion and because both HTML and Idoc Script support both single and double quotes for quoting, it is sometimes a good idea to switch between the two for nesting constructs.

Note the usage of the xml function. This guarantees that the input field's value is a well-formed HTML literal string construct. In this particular case, it is not needed. But for more complex constructs it can be helpful.

2.4 Overview of EventTrigger Fields

Topics

2.4.1 About Using EventTrigger Fields

The value for the EventTrigger field should be set in a binary format, that is, 0 to turn off and 1 to turn on event notifications for any listed operations/actions performed on a particular document/folder.

Each bit is independent of itself, so no relationship exists between any of these bits. The total length of the field is “N” bits (N = X+Y+Z). The first “X” bits on the left-hand side defines the event generation mechanism for certain pre-defined common operations performed on both documents and folders. The next set of “Y” bits and “Z” bits defines the event generation mechanism for pre-defined operations performed on an item (document/folder) that are very specific to folders and documents respectively.

The graphic shows flag used for each bit.

Note:

XXX: These bits are reserved for future use if new functionality/operations are to be notified.

You can configure X bits, Y bits, and Z bits as discussed in the following topics.

Configuring X Bits (Common Bits)

The graphic shows the configuration of X Bits.

  • NEW: This bit indicates that an event should be notified during the creation of an item (check-in of a document or create of a new folder).

  • UPDATE: This bit indicates that an event should be notified whenever a document/folder metadata has been updated.

  • COPY: This bit indicates that an event should be notified whenever the copy operation is performed on a document/folder.

  • MOVE: This bit indicates that an event should be notified whenever the move operation is performed on a document/folder.

  • DELETE: This bit indicates that an event should be notified whenever the delete operation is performed on a document/folder.

  • ADD_SHORTCUT: This bit indicates that an event should be notified whenever a new shortcut is created for a document/folder.

Configuring Y Bits for Folder Items

The graphic shows the configuration of Y Bits.

  • NEW_CHILD_ITEM: This bit indicates that an event should be notified whenever an immediate new child item (document/sub-folder) has been added to a folder.

  • CHILD_UPDATE: This bit indicates that an event should be notified whenever an immediate child item’s metadata is updated.

  • CHILD_REMOVE: This bit indicates that an event should be notified whenever an immediate child item has been removed (either by move or delete) from a folder.

  • NEW_CHILD_SHORTCUT: This bit indicates that an event should be notified whenever a new shortcut is created for an immediate child item.

Configuring Z Bits for Document Items

The graphic shows the configuration of Z Bits.

  • FILE: This bit indicates that an event should be notified whenever the FILE operation is performed on a document. That is, whenever a document becomes part of framework folders an event should be notified.

  • UNFILE: This bit indicates that an event should be notified whenever the UNFILE operation is performed on a document. That is, whenever a document is moved out of framework folders an event should be notified.

  • NEW REVISION: This bit indicates that an event should be notified whenever a new revision is added/created for a document.

  • DELETE REVISION: This bit indicates that an event should be notified whenever a revision is deleted/removed from a document.

2.4.2 The EventTrigger Field Value Inheritance Mechanism

The EventTrigger field value inheritance mechanism is based on the type of the item.

The field value inheritance mechanism is applicable only to those items that the following conditions:

  • The item doesn’t have any value set for the EventTrigger field.

  • The item belongs to the FrameworkFolders component and is part of Enterprise Libraries.

Field Value Inheritance for Folder(s)

When a folder is part of any enterprise library, and if the value for the EventTrigger field is not explicitly set on it, then the value is inherited from the enterprise library to which the folder belongs. This library must be defined as the value for the EventTrigger field. It shouldn’t be from the immediate parent folder, even if the parent folder has overridden the value for the EventTrigger field.

In this diagram, the EventTrigger field’s value set on LIBRARY_1 is applicable/inherited to all the sub-folders in its hierarchy except FOLDER_11 which has overridden the value of the EventTrigger field.

Sub-folders in its hierarchy except FOLDER_11

Field Value Inheritance for Document(s)

When a document is part of any enterprise library, and if the value for the EventTrigger field is not explicitly set on it, then the value can be inherited from either:

  • The immediate parent folder to which the document belongs, only if the parent folder has overridden the value for theEventTrigger field. This gets precedence over the next point.

  • The enterprise library to which the document folder belongs, only if the library has value defined for the EventTrigger field.

In this diagram, the EventTrigger field’s value set on LIBRARY_1 is applicable/inherited to all the documents in its hierarchy except DOC_11, as the parent folder FOLDER_11 of DOC_11 has overridden the value of the EventTrigger field. Hence, the FOLDER_11 value is applicable for DOC_11.

Documents in its hierarchy except DOC_11