33 Customizing the DesktopTag Component
This chapter describes how to customize the DesktopTag component of Oracle WebCenter Content Server to specify properties for checked out versions of Microsoft Word, Excel, and PowerPoint files.
This chapter includes the following sections:
33.1 About the DesktopTag Component
DesktopTag is a 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 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 Configuring the DesktopTag Component.
The custom properties provide information about where a content item resides in 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 Content Server after check-out; for example, in an external workflow (that is, one that is not managed by 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.
33.2 Enabling the DesktopTag and OracleCleanContent Components
The DesktopTag component is included with Content Server 11gR1. It must be enabled on 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 Content Server installations.
You can enable components using Component Manager, which is accessible through the Administration, Admin Server, Component Manager menu option. For more information about enabling components, see Enabling and Disabling a Component in Oracle Fusion Middleware Administering Oracle WebCenter Content.
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
33.3 Checking Out and Checking In Content Items with DesktopTag
The DesktopTag component modifies the check-out (file get) and check-in operations for Content Server.
33.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.
33.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 ResultSet 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.
33.4 Adding Properties to Checked-Out Content Items
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.
The properties that are added to the Microsoft Office files depend on the settings in the DesktopTag configuration file (see Configuring the DesktopTag Component). In Figure 33-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 Content Server again.
Figure 33-1 shows an example of a Word 2003 document without any custom properties that DesktopTag would add.
Figure 33-1 Word 2003 Document Without Custom Properties Added by DesktopTag
Description of "Figure 33-1 Word 2003 Document Without Custom Properties Added by DesktopTag"
Figure 33-2 shows a number of custom properties added to a Word 2003 document.
Figure 33-2 Word 2003 Document with Custom Properties Added by DesktopTag
Description of "Figure 33-2 Word 2003 Document with Custom Properties Added by DesktopTag"
33.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 33-3 shows the custom properties that DesktopTag has added to a Word 2003 document.
Figure 33-3 Custom Document Properties (Microsoft Word 2003)
Description of "Figure 33-3 Custom Document Properties (Microsoft Word 2003)"
33.4.2 Checking In Documents from Outside Content Server
These custom document properties enable Oracle Webcenter Content: Desktop to keep track of where a managed file resides in Content Server. This, in turn, enables users to check a Microsoft Office document back in to Content Server even from outside a content management integration context.
To check in a document, the user must have a connection to the server set up. The Office add-in looks at the CGI URL, Server, and IDCNAME properties to try to match the document to a server, so the user must be on the same network and have access to the server.
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 email.
- 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 WebCenter Content menu or ribbon in Word. Desktop checks the custom properties embedded in the Word document to find out where to upload the file to.
33.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/WCC_ORACLE_HOME/ucm/idc/components/DesktopTag.
Note:
Make sure that you restart Content Server after making changes to the DesktopTag configuration file.
The following properties can be set in the configuration file:
DesktopTagFormatsDesktopTagPrefixDesktopTagFieldsDesktopTagPrefixCustomDesktopTagFieldsCustomDesktopTagPrefixExtendedDesktopTagFieldsExtendedDefaultTaskPaneUrlDesktopTagLogDesktopTagFormatsExclude
33.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.
33.5.2 DesktopTagPrefix Property
The value of the DesktopTagPrefix property is the prefix added to the names of all standard Content Server metadata fields in the list of standard DesktopTag fields (see 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
33.5.3 DesktopTagFields Property
The value of the DesktopTagFields property is a comma-separated list of all standard 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). For information about the internal field names of the standard metadata field, see Configuration Variables in Oracle Fusion Middleware Configuration Reference for Oracle WebCenter Content.
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 33-4 shows the result of the preceding DesktopTagFields definition (assuming the default DIS prefix is used).
Note:
The DISProperties custom property is always added. Its value is a list of all properties added by DesktopTag.
33.5.4 DesktopTagPrefixCustom Property
The value of the DesktopTagPrefixCustom property is the prefix added to the names of all custom Content Server metadata fields in the list of custom DesktopTag fields (see 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
33.5.5 DesktopTagFieldsCustom Property
The value of the DesktopTagFieldsCustom property is a comma-separated list of all custom 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 DesktopTagFields Property).
Example: DesktopTagFieldsCustom=xComments(Extra Info),xArchiveStatus
Note:
The standard and custom 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.
33.5.6 DesktopTagPrefixExtended Property
The value of the DesktopTagPrefixExtended property is the prefix added to the names of all custom Content Server metadata fields in the list of extended DesktopTag fields (see 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
33.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 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.
33.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 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.
33.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 Content Server log files (accessible from the server's administration pages), as Figure 33-5 shows.
Figure 33-5 DesktopTag Event in Content Server Log File
Description of "Figure 33-5 DesktopTag Event in Content Server Log File"
33.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.