Oracle® Fusion Middleware Developer's Guide for Oracle Universal Content Management 11g Release 1 (11.1.1) E10807-03 |
|
![]() Previous |
![]() Next |
Home > Developer's Guide for Oracl... > Customizing DesktopTag
This chapter describes how to customize the DesktopTag component of Oracle Content Server to specify properties for checked out versions of Microsoft Word, Excel, and PowerPoint files.
This chapter includes the following sections:
DesktopTag is an Oracle Content Server component that manages custom properties in files created using the default formats of Microsoft Office applications (2002 or later versions). The component adds custom properties to Word documents (DOC, DOCX, and DOT files), Excel spreadsheets (XLS, XLSX, and XLT files), and PowerPoint presentations (PPT and PPTX files) when they are checked out of Oracle Content Server, and removes this information when they are checked in again.
The properties to be added to the Microsoft Office files are specified in the DesktopTag configuration file. For more information, see Section 13.5, "Configuring the DesktopTag Component."
The custom properties provide information about where a content item resides in Oracle Content Server so that the file can be checked in to the right location, with the right content management parameters, and so on. This is particularly useful if the content item is processed outside of Oracle Content Server after check-out; for example, in an external workflow (that is, one that is not managed by Oracle Content Server). Also, the information can be exposed to users; for example, in the task area of Microsoft Office applications.
DesktopTag uses the Oracle Clean Content technology to add custom properties to and remove them from Microsoft Office files.
The DesktopTag component is included with Oracle Content Server 11gR1. It must be enabled on Oracle Content Server because it is not enabled by default. The DesktopTag component requires that the OracleCleanContent component is enabled as well. The OracleCleanContent component is enabled with typical Oracle Content Server installations.
You can enable components using Component Manager, which is launched from the Content Admin Server page. For more information about enabling components, see "Enabling and Disabling a Component" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.
DesktopTag can add custom properties to the following Microsoft Office applications:
Microsoft Word 2002 (XP) and later versions
Microsoft Excel 2002 (XP) and later versions
Microsoft PowerPoint 2002 (XP) and later versions
The DesktopTag component modifies the check-out (file get) and check-in operations for Oracle Content Server.
The DesktopTag component installs a service handler override for the createFileName method, which should be called for all file get operations that go through the server (native URL requests do not call this method). If the file type is supported by the configuration, a set of custom properties are added to the file. These custom properties are used in various ways by the DesktopIntegrationSuite component and are made available to other components.
The DesktopTag component installs an extension filter that hooks the validateCheckinData filter, which is part of the DesktopIntegrationSuite component. It removes the custom properties that were added by a file get operation before the data is checked in to the server.
The result set returned for this operation includes the properties that would be added to the Microsoft Office file in a subsequent file get operation. This is provided to allow the client to modify the file rather than having to get a new copy. This method calls the desktopTagGetFilter extension filter, just like the file get operation.
The functionality offered by the DesktopTag component is provided entirely in the background. There is no direct user interaction. It is typically used for content tracking purposes, although the information can be exposed to users.
Figure 13-1 shows an example of a Word 2003 document without custom properties added by DesktopTag, and Figure 13-2 shows a number of custom properties added.
The properties that are added to the Microsoft Office files depend on the settings in the DesktopTag configuration file (see Section 13.5, "Configuring the DesktopTag Component"). In Figure 13-2, the content ID (dDocName), user name (dUser), and unique content item identifier (dID) are added to the Word document. The DISProperties custom property is always added. It lists all custom properties added by DesktopTag (as specified in the configuration file), and is used to ensure that the correct custom properties are deleted when a file is checked into Oracle Content Server again.
Users can view the custom properties of a Microsoft Office file as follows:
Microsoft Office XP (2002) and 2003: Choose File, then Properties, and then click the Custom tab.
Microsoft Office 2007: Click the Office button in the application, then choose Prepare, then Properties, then Document Properties, then Advanced Properties, and then click the Custom tab.
Microsoft Office 2010: Open the File panel, then click Info, then Properties, then Advanced Properties, and then click the Custom tab.
Figure 13-3 Custom Document Properties (Microsoft Word 2003)
These custom document properties allow Desktop Integration Suite to keep track of where a managed file resides in an Oracle Content Server instance. This, in turn, enables users to check a Microsoft Office document back in to Oracle Content Server even from outside a content management integration context. This feature can be useful in a number of situations; for example:
A user receives a managed Word document from someone else, as an attachment to an e-mail.
A user copies a managed Word document from a server in the integration hierarchy to a folder outside that hierarchy.
In either case, users can open the file in Microsoft Word, make changes, and then check the file back in to the server using the Oracle UCM menu or ribbon in Word. Desktop Integration Suite checks the custom properties embedded in the Word document to find out where to upload the file to.
The DesktopTag component is configured using a configuration file, desktoptag_environment.cfg, which is located in the component installation directory. This is a plain-text file that you can edit in any text editor. The component installation directory is MW_HOME/ECM_ORACLE_HOME/ucm/idc/components/DesktopTag.
Note: Make sure that you restart Oracle Content Server after making changes to the DesktopTag configuration file. |
The following properties can be set in the configuration file:
DesktopTagFormats
DesktopTagPrefix
DesktopTagFields
DesktopTagPrefixCustom
DesktopTagFieldsCustom
DesktopTagPrefixExtended
DesktopTagFieldsExtended
DefaultTaskPaneUrl
DesktopTagLog
DesktopTagFormatsExclude
The value of the DesktopTagFormats
property is a comma-separated list of MIME data types that are processed for tagging. If the data type is not in the list, it is not processed. If this parameter is commented out (using #
), empty, or not included in the configuration file at all, then all supported data types are processed.
Example: DesktopTagFormats=application/msword,application/ms-excel
If you include a nonsupported MIME data type in the list, DesktopTag will attempt to process the file, and an error event is included in the log file if logging is enabled.
The value of the DesktopTagPrefix
property is the prefix added to the names of all standard Oracle Content Server metadata fields in the list of standard DesktopTag fields (see Section 13.5.3, "DesktopTagFields Property"). This prefix is not added if a specific property name is defined.If this parameter is commented out (using #
), empty, or not included in the configuration file at all, then DIS
is used as the default.
Example: DesktopTagPrefix=STD
The value of the DesktopTagFields
property is a comma-separated list of all standard Oracle Content Server metadata fields that are added to Microsoft Office files as custom properties. You should use the server-internal field names (for example, dDocName
for the content ID). See the Oracle Fusion Middleware Idoc Script Reference Guide for the internal field names of the standard metadata fields.
You can set a specific property name for a metadata field by adding it in parentheses after the field name. This is especially useful if the property name will be exposed to end users (for example, in the task area in Microsoft Office 2007 applications).
Example: DesktopTagFields=dID,dDocName,dUser(User Name)
Figure 13-4 shows the result of the preceding DesktopTagFields
definition (assuming the default DIS
prefix is used).
The value of the DesktopTagPrefixCustom
property is the prefix added to the names of all custom Oracle Content Server metadata fields in the list of custom DesktopTag fields (see Section 13.5.4, "DesktopTagPrefixCustom Property"). This prefix is not added if a specific property name is defined.
If this parameter is commented out (using #
), empty, or not included in the configuration file at all, then DISC
is used as the default.
Example: DesktopTagPrefixCustom=CST
The value of the DesktopTagFieldsCustom
property is a comma-separated list of all custom Oracle Content Server metadata fields that will be added to Microsoft Office files as custom properties. You define these fields in exactly the same manner as standard metadata fields (see Section 13.5.3, "DesktopTagFields Property").
Example: DesktopTagFieldsCustom=xComments(Extra Info),xArchiveStatus
The value of the DesktopTagPrefixExtended
property is the prefix added to the names of all custom Oracle Content Server metadata fields in the list of extended DesktopTag fields (see Section 13.5.7, "DesktopTagFieldsExtended Property"). This prefix is not added if a specific property name is defined.
If this parameter is commented out (using #
), empty, or not included in the configuration file at all, then DISX
is used as the default.
Example: DesktopTagPrefixExtended=EXT
The value of the DesktopTagFieldsExtended
property is a comma-separated list of property definitions that come from the ExtendedUserAttributes component. The general form of a property definition is type
/
key
/
subkey
(
name
)
. The type
, key
, and subkey
values are the parameters used by the EC_GET_PROPERTY service. If any of these values begins with the character @
, then the parameter value is taken from the specified Oracle Content Server metadata field (see the following example).
You can set a specific property name for a metadata field by adding it in parentheses after the field name.
Example: DesktopTagFieldsExtended=account/@dSecurityGroup/WCTPUrl (DIS_Task_Pane_Url)
This example specifies that the property will be named DIS_Task_Pane_Url
, and its value will be the ExtendedUserAttributes
item with the type account
, the key value specified by the dSecurityGroup
metadata field (the security group of the content item), and the subKey WCTPUrl
.
The value of the DefaultTaskPaneUrl
property is a string that defines the default URL to use in setting the DISTaskPaneUrl
property, which is required to display a web page for a file in the task area of Microsoft Office applications. Any words beginning with the character @
are replaced by the values from the binder or by other means (currently, this applies only to @cgiUrl
).
Example: DefaultTaskPaneUrl=@cgiUrl?IdcService=GET_TASK_PANE &dID=@dID
In this example, @cgiUrl
would be replaced by the Oracle Content Server Cgi URL value, and @dID
would be replaced by the value of the server-internal, unique content item identifier (dID
).
As another example, if there is an extended user attribute called WebCenterUrl
, then adding the string "WebCenterUrl(DISTaskPaneUrl)"
will set the DISTaskPaneUrl
property to the value of the extended user attribute called WebCenterUrl
.
The value of the DesktopTagLog
property is a Boolean value that indicates whether or not to log the operations and results of the DesktopTag component (1
= yes, 0
= no).
If this parameter is commented out (using #
), empty, or not included in the configuration file at all, then the component operations and results are not logged. The DesktopTag log information is included in the standard Oracle Content Server log files (accessible from the server's administration pages).
The value of the DesktopTagFormatsExclude
property is a comma-separated list of MIME data types that are not processed for tagging. If the data type is not in the list, it is processed.
Example: DesktopTagFormatsExclude=application/ms-excel
There is no reason to use both DesktopTagFormats
and DesktopTagFormatsExclude
.