This chapter describes Microsoft Component Object Model (COM) integration. Oracle WebCenter Content Server utilizes a COM-based API, which provides the capability to call functionality from within a COM environment.
This chapter includes the following sections:
You can use a COM interface to integrate Content Management with Microsoft environments and applications. An ActiveX control and an OCX component are provided as interface options to gain access to the content and content management functions within Content Server. Additionally, you can communicate with ODMA-aware applications through a COM interface.
An Object Linking and Embedding Control Extension (OCX) control is provided for connecting to a remote Content Server instance and executing Content Server services. The IdcClient OCX control is used within a Windows Visual Basic development environment to gain access to the content and content management functions within Content Server.
You can call Content Server services with the IdcClient OCX control. The IdcClient.ocx
control is used to connect to a remote Content Server instance and perform typical server functions.
Note:
A Visual Basic or Visual C++ development environment is required for using the IdcClient OCX component.
The IntradocClient OCX component is used within a Windows Visual Basic development environment to gain access to the content and content management functions within Content Server. The OCX integration is designed to call services in a visual development environment, or to connect to a remote Content Server instance.
The IntradocClient OCX component provides functionality that you can access with a method call. Methods perform actions and often return results. Information is passed to methods using parameters. Some functions do not take parameters; some functions take one parameter; some take several.
The IntradocClient OCX component requires a username and password to execute the commands. The user must have the appropriate permissions to execute the commands. Some commands will require an administrative access level, other commands may require only write permission.
Outside of the init
and connection
managing methods, all methods use the serialized HDA format for communication. The returned serialized HDA format string contains information about the success or failure of the command. The StatusCode
will be negative if a failure occurs, and StatusMessage
indicates the error.
For more information, see the Oracle Fusion Middleware Services Reference for Oracle WebCenter Content. This guide also contains information about the IntradocClient OCX API specifications listing the properties, methods, and events.
IdcClient is an ActiveX control that allows a program to perform actions such as executing a service and retrieving file path information. The IdcClient control is also a wrapper for the Microsoft Internet Explorer browser.
The IdcClient OCX control is designed to use the Unicode standard and in most cases exchanges data with Content Server in UTF-8 format. Unicode uses two bytes (16 bits) of storage per character and can represent characters used in a wide range of languages (for example, English, Japanese, Arabic). Since English language ASCII (American Standard Code for Information Interchange) characters only require one byte (8 bits), when an ASCII character is represented the upper byte of each Unicode character is zero.
See the Unicode Consortium on the Web for additional information about the Unicode standard at http://www.unicode.org
.
Note:
IdcClient OCX is built atop the Microsoft Layer for Unicode, which allows Unicode applications to run on Win9x platforms. When distributing the IdcClient OCX Control on 9x platforms, the "unicows.dll" must also be distributed. This companion DLL cannot be distributed on Windows-based systems.
In most cases, the methods use the serialized HDA format for communication. A serialized HDA format is a Java method used for communication. The returned serialized HDA
format string contains information about the success or failure of the command.
The IdcClient OCX control provides functionality that can be performed with a method call. Methods perform actions and often return results. Information is passed to methods using parameters. Some functions do not take parameters; some functions take one parameter; some take several. For example, a function with two parameters passed as strings would use this format:
Function(Parameter As String, Parameter As String) As String
IdcClient OCX enables users to write client applications to execute services. The OCX control takes name/value pairs containing commands and parameters and calls the specified services. Execution results are passed back to the calling program.
IdcClient OCX requires a user name and password to execute the commands. The user must have the appropriate permissions to execute the commands. Some commands will require an administrative access level, other commands may require only write permission.
For more information, see the Oracle Fusion Middleware Services Reference for Oracle WebCenter Content.
Events are executed when the user or server performs an action. For example:
The IntradocBrowserPost
event executes every time a user submits a form from within a browser.
The IntradocServerResponse
event executes after the server completes a requested action.
The Visual Basic Standard Controls provide methods that are common to every Visual Basic development environment. In addition, the IdcClient OCX control provides methods that are private and unique to this specific control. These methods are used to perform or initiate an action rather than setting a characteristic.
For example:
The AboutBox()
method launches the About box containing product version information.
The GoCheckinPage
method checks in a new content item or a content item revision.
Properties describe or format an object and can be modified with code or by using the property window in the Visual Basic development environment. Properties describe the basic characteristic of an object.
For example:
The UserName
property provides the assigned user name.
The WorkingDir
property specifies the location where downloaded files are placed.
The IdcClient OCX control is used within a Windows Visual Basic development environment to gain access to the content and content management functions within Content Server. The OCX integration is designed to call services in a visual development environment, or to connect to a remote Content Server instance.
In most cases, methods use the serialized HDA format for communication. The returned serialized HDA format string contains information about the success or failure of the command. The StatusCode
will be negative if a failure occurs, and StatusMessage
will indicate the error. If the returned HDA does not contain a StatusCode
parameter, the service call succeeded.
You can set up the IdcClient OCX component and create a visual interface in the Microsoft Visual Basic development environment.
Follow these steps to set up the IdcClient OCX component in the Microsoft Visual Basic development environment:
The following procedure for creating a visual interface is based on the assumption that a Visual Basic project has been created and the IdcClient OCX control has been placed in the list of controls. For more information, see Setting Up the IdcClient OCX Component.
Follow these steps to build a basic visual interface:
Select the control, and draw it on the Visual Basic form.
Figure 28-1 shows the IdcClient OCX control.
Figure 28-1 OCX Control Drawn on a Visual Basic Form
From the drop-down list of the Properties window, choose IdcClient OCX.
If the Properties window is not currently displayed, select View, and then choose Properties Window from the main menu.
Rename the IdcClient OCX control IdcClientCtrl.
Define HostCgiUrl to reference the iss_idc_cgi.dll
for your particular instance.
For example:
http://testserver/intradoc-cgi/iss_idc_cgi.dll
Figure 28-2 shows this URL as the value of HostCgiUrl.
On the form, draw a text box, and name it CgiUrl
.
For the Text field, enter the HostCgiUrl value as the text to be displayed, such as http://testserver/intradoc-cgi/iss_idc_cgi.dll
.
Figure 28-3 shows this URL as the Text value.
Figure 28-3 Edited CgiUrl TextBox Properties
On the form, draw a text box, and name it Command
.
Clear the entry for the Text field (leave blank), and set MultiLine to True
.
Figure 28-4 shows a MultiLine value.
Figure 28-4 Edited Command TextBox Properties
On the form, draw a text box, and name it Response
.
Clear the entry for the Text field (leave blank).
Figure 28-5 shows field values for a Response
text box.
Figure 28-5 Edited Response TextBox Properties
On the form, draw a button, and name it SendPostCommand
.
For the Caption field, enter Send Post Command
as the text to be displayed.
Figure 28-6 shows a Caption value to be displayed on a SendPostCommand
button.
Figure 28-6 Edited SendPostCommand CommandButton Properties
On the form, select View, and then choose Code.
Select SendPostCommand, and then click the drop-down lists and modify the code to perform these actions:
Set the Host Cgi URL value.
Issue the command.
(Optional) Replace LF with CRLF to make the presentation in the edit control more readable.
Display the response.
Modify the code as follows:
Dim R As String IdcClientCtrl.HostCgiUrl = CgiUrl.Text R = IdcClientCtrl.1.SendPostCommand(Command.Text) R = Replace(R, vbLf, vbCrLf Response.Text = R
Figure 28-7 shows the code modifications.
Figure 28-7 Edited SendPostCommand_Click Code
Choose Form and then Load from the drop-down lists, and add the following lines to set the login prompt for the Content Server instance:
IdcClientCtrl.UseBrowserLoginPrompt = True IdcClientCtrl.UseProgressDialog = True
Figure 28-8 shows the modified code.
(Optional) Add appropriate descriptive labels, such as Cgi Url, Command, and Response
Figure 28-9 shows a form with descriptive labels.
Figure 28-9 Visual Interface with a Descriptive Label
Select Run, and then choose Start to test the visual interface.
Figure 28-10 shows a successful test result.
Enter a formatted command in the Command field.
Figure 28-11 shows the ADD_USER
command to add a user.
For more information about the ADD_USER
service, see the Oracle Fusion Middleware Services Reference for Oracle WebCenter Content.
Figure 28-11 Visual Interface with Defined Command
Click the Send Post Command button to execute the command. The returned results are displayed in the Response field.
Figure 28-12 shows some returned results.
Figure 28-12 Visual Interface with Returned Results
To verify the command:
user99
).Events are executed when the user or server performs an action. The following IdcClient OCX events are available:
Executes before a file is downloaded.
Initiates the server actions and updates required before a download.
Parameters
The event passes these parameters:
ByVal params
As String
cancelDownload
As Boolean
Executes every time a form is submitted from within a browser.
Parameters
The event passes these parameters:
ByVal url
As String
ByVal params
As String
cancelPost
As Boolean
Executes whenever the browser state changes.
Parameters
The event passes these parameters:
ByVal browserStateItem
As String
ByVal enabled
As Boolean
Executes a request for a progress report to be sent from the server. This event occurs only after a method has been called.
Parameters
The event passes these parameters:
ByVal statusData
As String
ByVal isDone
As Boolean
Executes after the server completes a requested action. For example, after a file has been downloaded. This event handles HDA encoded data that is a response from the server. This event only occurs when an action is performed in the browser.
Parameters
The event passes one parameter:
ByVal response
As String
The following IdcClient OCX methods are available:
Methods marked with an asterisk (*) are ones which are not related to browser activity and which return a value.
Note:
All parameters are required unless otherwise indicated.
Sub AboutBox()
Description
Launches the About box containing product version information.
FALSE
if the call cannot be executed.Parameters
None
Sub Back()
Description
Displays the previous HTML page.
Parameters
None
Function CancelRequest() As Boolean
Description
This method cancels the currently active request. Returns FALSE
if the function is unable to cancel the request or if there is no request currently active.
Parameters
None
Output
Returns a Boolean value:
TRUE
if request is canceled.FALSE
if the cancel request is not performed.Sub DoCheckoutLatestRev(docName As String, curID As String)
Description
Checks out or locks the latest content item revision.
Given a content item name and the version label, the method checks out the latest content item revision.
Executes the IntradocServerResponse
event. The event is executed before the method occurs. For details, see IdcClient Events.
Note:
The curID
value is the content item version label, not the generated content item revision ID.
This function returns the following values:
Serialized HDA containing dID
and dDocName
.
FALSE
if the latest revision cannot be checked out or cannot be found in the system.
The data that was passed in as parameters.
Parameters
docName: The user-assigned content item name.
curID: The unique identifier for the latest revision. Optional.
Function DownloadFile(command As String, filename As String) As String
Description
Downloads the defined file.
Given a currently associated command and the file type, this method performs a file download of the postconversion file (compare DownloadNativeFile
).
Executes the IntradocBeforeDownload
event. The event is executed before the method occurs. For details, see IdcClient Events.
This function returns the following:
Serialized HDA containing the status code and status method.
The data that was passed in as parameters.
FALSE
if it is unable to download the specified file.
Parameters
command: The currently associated command.
filename: The file format. This is the file type such as PDF, HTM, or other supported format.
Function DownloadNativeFile(id As String, docName As String, filename As String) As String
Description
Downloads the defined native file.
Given a content item revision ID, a content item name, and a file type, this method performs a file download of the native file (compare DownloadFile
).
Executes the IntradocBeforeDownload
event. The event is executed before the method occurs. For details, see IdcClient Events..
Note:
The id
value is the generated content item revision ID, not the content item version label.
This function returns the following:
Serialized HDA containing dID
and dDocName
.
The data that was passed in as parameters.
FALSE
if it is unable to download the specified file.
Parameters
id: The unique identifier for the latest revision.
docName: The user-assigned content item name.
filename: The file format. This is the file type such as DOC, RTF, or any other supported format.
Sub Drag([nAction])
Description
Begins, ends, or cancels a drag operation.
The Drag
method is handled the same as a Standard Control implementation.
Refer to a Visual Basic API reference for additional information.
Parameters
nAction: Indicates the action to perform. If you omit nAction
, nAction
is set to 1.
The settings for the Drag
method are:
0: Cancel drag operation; restore original position of control.
1: (Default) Begin dragging the control.
2: End dragging, that is, drop the control.
Sub EditDocInfoLatestRev(docName As String, curID As String, activateAction As String)
Description
Edits the content item information for the latest revision.
ODMA related.
Given a content item name, the version label, and the currently active requested action, the method edits the content item information for the latest revision.
The function returns FALSE
if the content item information for the latest revision cannot be edited or cannot be found in the system.
Note:
The curID
value is the content item version label, not the generated content item revision ID.
Parameters
curID: The unique identifier for the latest revision.
activateAction: Passed to ODMActivate. This can be used as Idoc Script. Optional.
docName: The user-assigned content item name. Optional.
Sub Forward()
Description
Displays the next HTML page.
Moves the user to the next screen.
This method retrieves cached information for the next HTML page for display to the user.
Parameters
None
Sub GoCheckinPage(id As String, docName As String, isNew As Boolean, params As String)
Description
Checks in a new content item or a content item revision.
Given the content item revision ID and the content item name, the function checks in a new content item or a content item revision.
This method opens the content item check-in page and enters the unique content item identifier, user-assigned content item name, and any assigned content item parameters into the associated text fields. It is also specified whether this is a new content item or a revision.
Note:
The id
value is the generated content item revision ID, not the content item version label.
Output
This function returns the following:
FALSE
if it is unable to check in the specified file.
Serialized HDA containing dID
and dDocName
.
The data that was passed in as parameters.
Parameters (All Optional)
id: The unique identifier for the latest revision.
docName: The user-assigned content item name.
IsNew: Defines whether the content item to be checked in is a new content item or a revision.
If TRUE
, a new unique content item version label is assigned.
Default is TRUE
.
params: The parameters that prefill the Check In page.
Sub Home()
Description
Returns the user to the defined home page.
Moves the user to the home screen.
Executes an HTML page request and displays the defined home page to the user.
Parameters
None
Function InitiateFileDownload(command As String, filename As String) As String
Description
Initiates a file download.
Given the currently associated command and the file type, the function initiates a file download. This method initiates a file download of a specific rendition of a content item, the latest revision, or the latest released revision.
Executes the IntradocServerResponse
event. The event is executed before the method occurs. For details, see IdcClient Events.
Parameters
command: The currently associated command.
filename: The file format. This is the file type, such as PDF
, HTM
, or another supported format.
Output
Returns serialized HDA containing the requested information.
Returns the data that was passed in as parameters.
Function InitiatePostCommand(postData As String) As String
Description
Initiates a post command.
Initiates a service call. Given assigned post data, this method initiates a post command.
Executes the IntradocServerResponse
event. The event is executed before the method occurs. For details, see IdcClient Events.
Parameters
postData: The serialized HDA containing the service command and any necessary service parameters.
Output
Returns serialized HDA containing the requested information.
Returns StatusCode
and StatusMessage
.
The StatusCode will be negative if a failure occurs, and StatusMessage will indicate the error.
If the returned HDA does not contain a StatusCode parameter, the service call succeeded.
Sub Move(Left As Single, [Top], [Width], [Height])
Description
Moves an object.
The Move
method is handled the same as a Standard Control implementation.
Refer to a Visual Basic API reference for additional information.
Parameters
nLeft: Specifies the horizontal coordinate for the left edge of the object. This is a single-precision value.
nTop: Specifies the vertical coordinate for the top edge of the object. This is a single-precision value.
nWidth: Specifies the new width of the object. This is a single-precision value.
nHeight: Specifies the new height of the object. This is a single-precision value.
Sub Navigate(url As String
Description
Computes the URL path.
Given a complete URL, this method computes the URL from the serialized HDA and returns the value as a string.
This function returns the following values:
Serialized HDA containing the requested information.
The data that was passed in as parameters.
Parameters
url: The complete URL path.
Sub NavigateCgiPage(params As String)
Description
Computes the CGI path.
Given defined content item parameters, this method computes the CGI path from the serialized HDA and returns the value as a string.
Parameters
params: The assigned content item parameters.
Description
Refreshes the browser.
This method refreshes the web browser and updates dynamic information.
Parameters
None
Function SendCommand(params As String) As String
Description
Issues a service request to Content Server.
Given defined content item parameters, the function executes a service from Content Server related to content item handling.
Parameters
params: The CGI URL encoded parameters.
Output
Returns serialized HDA containing the requested information.
Returns the data that was passed in as parameters.
Function SendPostCommand(postData As String) As String
Description
Sends a post command.
Executes a service call.
Executes the IntradocBrowserPost
event. The event is executed before the method occurs. For details, see IdcClient Events.
Parameters
postData: The serialized HDA containing the service command and any necessary service parameters.
Output
Returns serialized HDA containing the requested information.
Returns StatusCode
and StatusMessage
.
The StatusCode
will be negative if a failure occurs, and StatusMessage
will indicate the error.
If the returned HDA does not contain a StatusCode parameter, the service call succeeded.
Sub SetFocus()
Description
Assigns the focus to a control.
The SetFocus
method is handled the same as a Standard Control implementation.
Refer to a Visual Basic API reference for additional information.
Parameters
None
Sub ShowDMS()
Description
Opens the HTML page associated with the Content Manager.
ODMA related.
Displays the Content Manager access page in a browser.
Parameters
None
Sub ShowDocInfoLatestRev(docName As String, curID As String, activateAction As String)
Description
Displays the content item information for the latest revision.
Note:
The curID
value is the content item version label, not the generated content item revision ID.
Parameters
docName: The user-assigned content item name.
curID: The unique identifier for the latest revision. Optional.
activateAction: The currently active requested action. Optional.
Sub ShowWhatsThis()
Description
Displays the What's This Help topic specified for an object with the WhatsThisHelpID property.
The ShowWhatsThis
method is handled the same as a Standard Control implementation.
Refer to a Visual Basic API reference for additional information.
Parameters
Object: Specifies the object for which the What's This Help topic is displayed.
Sub StartSearch()
Description
Displays the query page in the browser control.
Preforms browser manipulation.
Parameters
None
Sub Stop()
Description
Stops the browser.
This method stops or cancels the loading of information in the browser.
Parameters
None
Sub UndoCheckout(docName As String, curID As String)
Description
This service reverses a content item checkout.
Given a content item name and a version label, this service attempts to locate the content item in the system and undo the check out. The service fails if the content item does not exist in the system, if the content item is not checked out or the user does not have sufficient privilege to undo the checkout.
Executes the IntradocServerResponse
event. The event is executed before the method occurs. For details, see IdcClient Events.
Note:
The curID
value is the content item version label, not the generated content item revision ID.
Parameters
curID: The unique identifier for the latest revision.
docName: The user-assigned content item name. Optional.
Sub ViewDocInfo(id As String)
Description
Navigates to the content item information page and displays content item information in a browser.
Performs browser manipulation.
Given a content item revision ID, the method displays content item information in a browser.
Note:
The id
value is the generated content item revision ID, not the content item version label.
Parameters
id: The unique identifier for the latest revision.
Sub ViewDocInfoLatestRev(docName As String, curID As String)
Description
Navigates to the content item information page and displays content item information for the latest revision.
Given a content item name and a version label, the method displays the content item information for the latest revision.
Note:
The curID
value is the content item version label, not the generated content item revision ID.
This function returns the following values:
Serialized HDA containing dID
and dDocName
.
The data that was passed in as parameters.
Parameters
docName: The user assigned content item name.
curID: The unique identifier for the latest revision.
Sub ZOrder([Position])
Description
Places a specified form or control at the front or back of the z-order within its graphical level.
The ZOrder
method is handled the same as a Standard Control implementation.
Refer to a Visual Basic API reference for additional information.
Parameters
nOrder: Specifies an integer indicating the position of the object relative to other objects. If you omit nOrder
, the setting is 0
.
The settings for the ZOrder
method follow:
0: (Default) The object is positioned at the front of the z-order.
1: The object is positioned at the back of the z-order.
The Open Document Management Application (ODMA) is a standard API used to interface between desktop applications and file management software. The ODMA integration for Content Server is available with Desktop, a separate product. Use the ODMA-integration products to gain access to the content and content management functions within Content Server (for ODMA-compliant desktop applications).
You can publish files to your web repository directly from any ODMA-compliant application, such as Microsoft Word, Corel WordPerfect, and Adobe FrameMaker. With the web-centric adoption of ODMA, you can check in and publish information directly to the Web. This is a significant advancement over traditional ODMA client/server implementations, where information is published first to a server and is not immediately available on the Web for consumption.
For more information, refer to the ODMA or ODMA/FrameMaker online help.
The ODMA Client is a separate product and does not ship with the core product. It is used to check in and publish information directly to the Web from your desktop applications. ODMA Client surpasses traditional ODMA client–server models, which publish information to a server and not immediately to the Web for consumption. You can use ODMA Client from within your desktop application to perform many tasks which interact with Content Server, for example:
Save a file and immediately check it in to Content Server.
Save a file to check in later.
Check out a file from Content Server.
Update a file's metadata (content information).
Save the file to your local file system and bypass the ODMA Client system.
These ODMA interfaces are available:
ODMA Client Interface: The Select Document screen with the Recent Files option selected displays a list of files that you recently used through ODMA. This screen is displayed instead of the typical Open dialog box. If a file does not display on this screen, you can search for it in Content Server or on the local file system.
ODMA Desktop Shell Interface: The Client Desktop Shell provides a drag-and-drop check-in functionality, and access to the ODMA Client - Select Document screen from outside of your desktop application. Through the Desktop Shell, you can:
Select a file from your desktop or a Windows Explorer window and drag it to the Desktop Shell to check in the file to Content Server.
Choose and open a file from the Recent Files list or from Content Server.
Content Server Interface with ODMA: You can open and check out an ODMA file directly from the Content Server Content Information page. When you open a file from Content Server, the file opens in its native application so that you can edit it and quickly check the file back in to Content Server.
Note:
You can also open and check out a file from within an ODMA-compliant application, and you can open a copy of a file instead of checking it out. For more information, see the ODMA Online Help.