13 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:

13.1 About the DesktopTag Component

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.

13.2 System Requirements

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

13.3 DesktopTag Component Operation

The DesktopTag component modifies the check-out (file get) and check-in operations for Oracle Content Server.

13.3.1 File Get Operation

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.

13.3.2 File Check-In Operation

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.

13.4 Using the DesktopTag Component

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.

Figure 13-1 Word 2003 Document Without Custom Properties Added by DesktopTag

Graphic showing Word 2003 Doc without custom properties

Figure 13-2 Word 2003 Document with Custom Properties Added by DesktopTag

Graphic showing Word 2003 Doc Properties

13.4.1 Viewing Custom Properties

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)

Description of Figure 13-3 follows
Description of "Figure 13-3 Custom Document Properties (Microsoft Word 2003)"

13.4.2 Checking in Documents from Outside Oracle Content Server

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.

13.5 Configuring the DesktopTag Component

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

13.5.1 DesktopTagFormats Property

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.

13.5.2 DesktopTagPrefix Property

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

13.5.3 DesktopTagFields Property

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

Figure 13-4 Example of Property Names

Surrounding text describes Figure 13-4 .

Note:

The DISProperties custom property is always added. Its value is a list of all properties added by DesktopTag.

13.5.4 DesktopTagPrefixCustom Property

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

13.5.5 DesktopTagFieldsCustom Property

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

Note:

The standard and custom Oracle Content Server metadata fields are processed exactly the same by DesktopTag. The separate configuration entries are there only to make it easier to distinguish between these fields.

13.5.6 DesktopTagPrefixExtended Property

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

13.5.7 DesktopTagFieldsExtended Property

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.

13.5.8 DefaultTaskPaneUrl Property

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.

13.5.9 DesktopTagLog Property

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

Figure 13-5 DesktopTag Event in Oracle Content Server Log File

Graphic of log file

13.5.10 DesktopTagFormatsExclude Property

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.