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:
Section 28.2, "Calling Content Server Services with the IntradocClient OCX component"
Section 28.3, "Using the ODMA API to Access Content Server from a Desktop Application"
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 Oracle WebCenter 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 Oracle WebCenter 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 Oracle WebCenter 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 Oracle WebCenter 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
.
Important:
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:
Create a new project.
Select Project, and then choose Components.
Browse to the IdcClient.ocx file on your system, and click Open.
The IdcClient module is added to the Component Controls list.
Ensure that the checkbox for the IdcClient ActiveX Control module is enabled, and click OK.
The IdcClient OCX control is placed in the list of controls.
(Optional) You can use the Visual Basic development environment to build your own visual interface or follow the steps provided in Section 28.2.3.2, "Creating a Visual Interface," to build a basic visual interface.
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 Section 28.2.3.1, "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.
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.
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.
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.
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.
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.
Choose Form and then Load from the drop-down lists, and add the following lines to set the login prompt for the Oracle WebCenter 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.
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.
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.
In a web browser, log in to Oracle WebCenter Content Server as an administrator.
In the Administration tray, choose Admin Applets.
Click User Admin. The applet launches and displays the added user (for example, 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.
The event passes these parameters:
ByVal params
As String
cancelDownload
As Boolean
Executes every time a form is submitted from within a browser.
The event passes these parameters:
ByVal url
As String
ByVal params
As String
cancelPost
As Boolean
Executes whenever the browser state changes.
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.
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.
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.
Important:
All parameters are required unless otherwise indicated.
Sub AboutBox()
Launches the About box containing product version information.
This method displays the product About box.
The method returns FALSE
if the call cannot be executed.
None
Sub Back()
Displays the previous HTML page.
Returns the user to the previous screen.
The method retrieves the previous HTML page from cached information for display to the user.
None
Function CancelRequest() As Boolean
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.
None
Returns a Boolean value:
Returns TRUE if request is canceled.
Returns FALSE if the cancel request is not performed.
Sub DoCheckoutLatestRev(docName As String, curID As String)
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 Section 28.2.4, "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.
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
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 Section 28.2.4, "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.
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
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 Section 28.2.4, "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.
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])
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.
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)
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.
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()
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.
None
Sub GoCheckinPage(id As String, docName As String, isNew As Boolean, params As String)
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.
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.
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()
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.
None
Function InitiateFileDownload(command As String, filename As String) As String
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 Section 28.2.4, "IdcClient Events."
command
: The currently associated command.
filename
: The file format. This is the file type, such as PDF
, HTM
, or another supported format.
Returns serialized HDA containing the requested information.
Returns the data that was passed in as parameters.
Function InitiatePostCommand(postData As String) As String
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 Section 28.2.4, "IdcClient Events."
postData: The serialized HDA containing the service command and any necessary service parameters.
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])
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.
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
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.
url: The complete URL path.
Sub NavigateCgiPage(params As String)
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.
params: The assigned content item parameters.
Refreshes the browser.
This method refreshes the web browser and updates dynamic information.
None
Function SendCommand(params As String) As String
Issues a service request to Oracle WebCenter Content Server.
Given defined content item parameters, the function executes a service from Oracle WebCenter Content Server related to content item handling.
params: The CGI URL encoded parameters.
Returns serialized HDA containing the requested information.
Returns the data that was passed in as parameters.
Function SendPostCommand(postData As String) As String
Sends a post command.
Executes a service call.
Executes the IntradocBrowserPost
event. The event is executed before the method occurs. For details, see Section 28.2.4, "IdcClient Events."
postData: The serialized HDA containing the service command and any necessary service parameters.
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()
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.
None
Sub ShowDMS()
Opens the HTML page associated with the Content Manager.
ODMA related.
Displays the Content Manager access page in a browser.
None
Sub ShowDocInfoLatestRev(docName As String, curID As String, activateAction As String)
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.
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()
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.
Object: Specifies the object for which the What's This Help topic is displayed.
Sub StartSearch()
Displays the query page in the browser control.
Preforms browser manipulation.
None
Sub Stop()
Stops the browser.
This method stops or cancels the loading of information in the browser.
None
Sub UndoCheckout(docName As String, curID As String)
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 Section 28.2.4, "IdcClient Events."
Note:
The curID
value is the content item version label, not the generated content item revision ID.
curID: The unique identifier for the latest revision.
docName: The user-assigned content item name. Optional.
Sub ViewDocInfo(id As String)
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.
id: The unique identifier for the latest revision.
Sub ViewDocInfoLatestRev(docName As String, curID As String)
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.
docName: The user assigned content item name.
curID: The unique identifier for the latest revision.
Sub ZOrder([Position])
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.
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.
Each data item or attribute is implemented as a property in Visual Basic. Properties are exposed through the Public Interface of an object within the Visual Basic development environment. These attributes can be used to further describe elements.
These are the IdcClient OCX properties:
Provides the user-supplied context value. This value becomes available to Idoc Script as the variable ClientControlled
in any web page delivered by Oracle WebCenter Content Server.
Returns the value as a string.
Takes no parameters.
Provides the complete URL path of the host CGI bin.
Returns the value as a string.
Takes no parameters.
Provides the assigned user password.
Returns the value as a string.
Takes no parameters.
Allows the use of a browser login prompt. Defines whether a dialog box for user authentication will display.
If set to TRUE
, control will open a dialog box for user authentication.
The default value is TRUE
.
Returns a Boolean value:
TRUE
if the login was successful
FALSE
if the login was denied
Enables the use of a user progress dialog. Defines whether a dialog box for user authentication will display.
If set to TRUE
, control will open a dialog box for user progress.
Default is TRUE
.
Returns a Boolean value:
Returns TRUE
if the action was completed.
Returns FALSE
if the action failed.
Provides the assigned user name.
Returns the value as a string.
Takes no parameters.
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 Oracle WebCenter Content Server, for example:
Save a file and immediately check it in to Oracle WebCenter Content Server.
Save a file to check in later.
Check out a file from Oracle WebCenter 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.