Deploying Smart Tags with Enterprise Applications

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

John R. Durant
Architechs

January 2002

Applies to:
     Microsoft® Office XP

Summary: How to deploy and manage smart tags in an enterprise setting using Office deployment tools. (12 printed pages)

Contents

Introduction
Initial Deployment Options
Management Best Practices
Update Mechanisms
Conclusion
About the Author
For Further Information

Introduction

Smart tag deployment can be simple in a small workgroup, but can have enormous implications in an enterprise setting. An organization with 50,000 desktops must consider the best way to deploy a smart tag to each desktop. How can the current Microsoft® Office deployment tools be used to facilitate this endeavor? How can updates to the smart tags be propagated to the desktops in an efficient manner? Network administrators and software support personnel must be sold on the idea that smart tags will not pose a burdensome load or they will not embrace their use. Microsoft Office XP gives end-users flexibility in using smart tags; how much of that functionality do administrators wish to keep? This paper will describe best practices with respect to smart tag deployment, maintenance, and installation.

At a high level, this paper addresses three critical parts of the smart tag deployment issues. The issues raised above can be segmented into these three categories that make up the body of this paper:

• Initial Deployment Options
• Management Best Practices
• Update Mechanisms

One of the main goals of smart tag technology is to increase the intelligence that coalesces around a document by recognizing terms in the document and proposing possible actions the user can take based on the recognized content. In this way, users can use the document as a point of departure for obtaining more knowledge and engaging in other operations. Thus, the extent to which knowledge workers receive these benefits depends on how well the smart tags are designed, whether they are installed on the users' desktops, and how easily those smart tags can be updated and maintained.

If the smart tags are difficult to install, compromise the integrity of a user's system, or become increasingly out of step with the knowledge needs of users, their benefit is lost. Moreover, if administrators find them to be difficult to deploy across the enterprise, they will never be broadly embraced.

Initial Deployment Options

Installing Office XP means that the user's desktop is now enabled with smart tag technology. There are also default smart tags that come installed with Office XP (see Table 1). You should read the Smart Tag SDK documentation in order to understand how to create custom smart tags and how to use list files with MOFL.DLL. Out of the box, Office XP installs several smart tag recognizer and action DLLs that can add instant productivity. Here is a list of these smart tags and some information about them:

Table 1. List of smart tag action and recognizer DLLs installed by default

This list of installed smart tag DLLs includes the MOFL.DLL which provides both the recognizer and the action interfaces to the Office application. Other DLLs provide one or the other, recognizer or action capability. Some of the action DLLs, like FPerson.DLL, support several types and are used by a recognizer built into the spelling/grammar engine of Microsoft Word. You can build and deploy your own recognizer that uses these same types and the verbs supported in the FPerson.DLL.

As you plan to go beyond the smart tags that are installed with Office XP, you have a few primary options. We will first look at the deployment options for a custom DLL and then look at options relating to the deployment of smart tag list files.

Registry Entries

Before a host application, such as Word or Excel, can use a smart tag DLL, it must be registered. Because the IsmartTagAction and ISmartTagRecognizer interfaces are implemented in a custom smart tag DLL, a ProgID (mapped to the CLSID) for each must be found in the registry. To be properly registered, the two following registry keys must have registration information for DLL's represented by the CLSID:

HKEY_CURRENT_USER\Software\Microsoft\Office\Common\Smart Tag\Actions
HKEY_CURRENT_USER\Software\Microsoft\Office\Common\Smart 
  Tag\Recognizers

In Figure 1 you can see the actual registry entries on a machine that has several custom smart tags installed.

Figure 1. Registry entries for custom smart tags

Note   Modifying the Microsoft Windows registry in any manner, whether through the Registry Editor or programmatically, always carries some degree of risk. Incorrect modification can cause serious problems that may require you to reinstall your operating system. It is a good practice to always back up a computer's registry first before modifying it. If you are running Microsoft Windows NT or Microsoft Windows 2000, you should also update your Emergency Repair Disk (ERD). For information about how to edit the registry, view the "Changing Keys and Values" Help topic in the Registry Editor (Regedit.exe) or the "Add and Delete Information in the Registry" and "Edit Registry Information" topics in the Registry Editor (Regedt32.exe).

At its simplest level then, deploying custom smart tags means getting the DLL and any other dependent files onto the client workstation and making the necessary registry entries. The higher goal is to make this as easy as possible, especially in an environment with potentially several thousand workstations.

Other registry entries include:

One of the things to watch for is whether you register your smart tag DLL by using the ProgID or the CLSID. When you create a smart tag DLL that implements both the interfaces for recognition and actions, a ProgID for both interfaces is created in the registry. The ProgID is mapped to a CLSID in the registry. The Status flag of your smart tag will not be updated when you modify its enabled/disabled state in the Office application. Consequently, you should always use CLSIDs and not ProgIDs when registering your smart tag DLLs. The Microsoft Knowledge Base article Q294422, BUG: Status Flag Is Not Updated When You Enable or Disable Smart Tags, describes how to register by CLSID instead of the ProgID.

There are a few other registry settings that can be used in configuring and controlling the smart tag environment on a local workstation. One has to do with the disabling of smart tag DLLs. Individual smart tag DLLs can be disabled for specific applications by setting a Status flag value in the registry. To disable a DLL in a host application, make the following adjustments to the Status subkey of the registry entry for a specific CLSID:

Keep in mind that users can change whether a smart tag is enabled or disabled in the AutoCorrect dialog box in the host application. If you want to prevent this, you will need to prevent registry access to users so that the status bits cannot be altered.

There is another registry setting that can be used to make it easier to inform users of new smart tags and point them to a download location. When users click the More Smart Tags button on the AutoCorrect dialog box, Microsoft Internet Explorer is launched and opens a Web site where new smart tags can be downloaded. The default site is an Office Update site. For example, for English versions, the URL is http://office.microsoft.com/office/redirect/10/smarttags.asp?HelpLCID=1033.

But, it can be administratively set using a registry key which points to a different site. This is done by changing the following subkey value:

HKEY_CURRENT_USER\Software\Microsoft\Office\Common\SmartTags\
  CheckForNewSmartTags

By changing the URL stored in this value and pointing users to an internal Web server that has downloadable smart tags, you can provide users with a convenient mechanism to access new smart tags as they are completed and rolled out.

Similar to this is the configuration of a download URL within a smart tag itself. When you implement the ISmartTagRecognizer interface, a property is exposed that permits the downloading of new smart tag actions. This is useful when users receive documents with embedded smart tags, but the action DLLs are not installed on the local machine. If the developer of the smart tag sets a value for the SmartTagDownloadURL property at design time, this property can be retrieved and used to download actions if they do not already have them installed for that particular smart tag.

There is a policy setting that allows administrators to redirect all executions of "Check for new actions…" to an internal Web site. This will prevent enterprise users from installing non-trusted actions/recognizers from outside the company's intranet. This key does not exist by default but can created at the following location in the registry:

HKEY_CURRENT_USER\Software\Microsoft\Office\Common\
  Smart tags\CheckForNewActions

If it's set, "Check for new actions…" will take the user to the URL specified in this key. This key allows you to override any "Check for new actions..." settings that may exist for a specific smart tag. Most enterprises maintain secure firewalls, and this setting permits you to control where users go to retrieve new smart tag DLLs irrespective of specific smart tag settings.

In each registry setting mentioned above, make sure that you list a full URL as the string value. For example, smarttagserver.ourcorp.com will not work as a download URL, but http://smarttagserver.ourcorp.com will. Another useful capability is that you can specify a UNC pathname as a valid download location for smart tags in these settings. So, your download directory could be \\smarttagserver\latestDLLs. Consider using system policies to configure these registry settings for smart tags on local workstations. A system policy can be particularly useful not only to set the worker's environment but also to change it as needed. With a policy in place, you can change registry settings by adjusting the policy as needed.

Microsoft Systems Management Server

Microsoft Systems Management Server (SMS) is can be used by enterprise administrators to deploy and maintain Microsoft Office XP on client computers. SMS is particularly useful in large or complex organizations where administrators need precise control over the deployment process. By using SMS, administrators can gain more detailed information about client workstations before installing Office XP or subsequent components like custom smart tag DLLs. If you have an organization where all workstations have not yet been upgraded to Office XP, you can find out which version is installed before continuing with your smart tag application installation.

This helps overcome one of the main weaknesses with any approach that requires the user to initiate the installation—users may not know whether their version of Office supports smart tags and they may erroneously attempt an installation that will not be supported. Using Systems Management Server can provide enterprise administrators with the following benefits:

• Ability to deploy to a large number of clients or across multiple sites
• Ability to push or force installation on client computers
• Means to deploy components to a mixture of Windows clients
• Means to deploy to users who do not have administrative rights on the local computer
• Greater control over the timing of the installation
• Advanced reporting and troubleshooting tools
• Easier maintenance when upgrades or other modifications to the smart tags are required

You can use SMS to install your smart tags after Office XP is already installed, but you can also use it to install Office XP itself. Note that you must have Systems Management Server 2.0 with Service Pack 2 to deploy Office XP. You may want to include your smart tags with the installation of Office XP so that once the deployment of Office is complete, users have all they need to begin using its full power in your enterprise. Over time, you can then add subsequently created smart tags and remove old ones that are no longer useful or needed.

Custom Installation Wizard

With the release of Office XP significant enhancements were made to the Custom Installation Wizard (CIW). These include enhanced dialog box control, new installation options and settings, and supplements to the Maintenance Wizard. The CIW, on the whole, is a useful tool for creating repeatable, yet custom, installations of Office XP on client workstations. To use the CIW, you set up an administrative installation point on your network from which users will launch the installation. With the CIW, you modify the administrative installation by configuring a Windows Installer transform (MST file). The original .msi package then uses this file in such a way that you can:

• Define the path where Office is installed on users' computers
• Define the default installation state for all features of Office applications. For example, you can choose to install Microsoft Word on the user's local hard disk and install Microsoft PowerPoint® to run from the network
• Add your own files and registry entries to Office Setup so that they are installed along with Office
• Modify Office application shortcuts, specifying where they are installed and customizing their properties
• Define a list of network servers for Office to use if the primary server is unavailable
• Specify other products to install, or programs to run, on users' computers after setup is completed

It is this last option, sometimes called chained installations, that holds particular interest for smart tag developers, because you can install additional components as part of the installation of Office XP. Within the dialog boxes for the CIW, you are given the chance to include additional programs that you may want to include as part of the Office XP installation. You can specify the .msi package for an add-in or other program that you want users to have. On the Add Installations and Run Programs page, you add your smart tag .msi file. When the custom installation of Office XP completes, the installation of your smart tag application will commence.

Microsoft Office Smart Tag List Tool

Use of the Microsoft Office Smart Tag List Tool (MOSTL) is documented in the Smart Tag SDK, and you should be familiar with how to properly use the tool in order to understand how to deploy smart tag list files in an enterprise. One of the greatest advantages of using MOSTL is that the requisite DLL for the smart tag is installed on the client workstation automatically as part of the installation of Office XP. The only item that must be installed for custom smart tag lists to work is a simple XML file that contains the recognition term list and the list of actions. There is also update capability built into the list file infrastructure, so the XML file may also contain few settings for the automatic update of the file contents via a URL.

Each of the mechanisms described in this paper so far can be used to deploy an XML file to a specific directory on a user's workstation:

• Using Windows Installer
• Using an ActiveX® control with Windows Installer
• Using the Custom Installation Wizard
• Using Microsoft Systems Management Server

The advantages and weaknesses of each mechanism are consistent even when deploying a smart tag list file. In addition, you could create your own custom mechanism for placing the file on a client's workstation. You could do this via a Web page that pulls down the latest XML file and a client-side script that places it on the appropriate directory on the client workstation. This works in an environment where you the browser on client workstations allows this type of script to run, and it exposes the inner-workings of the script. This is one reason why using an ActiveX control to either run an .msi or manual manipulate the files may be a better option. There are many ways to download XML files and save them to a local disk, and you should consider them carefully in the context of your enterprise network and security requirements. Remember that XML files are plain text content files. The information they contain can be easily read unless you encrypt them in some way. Encryption, while it will provide a level of security, does require more resources and planning to be used effectively.

Management Best Practices

In this article, we have described a few of the ways that you can use to deploy smart tags. Each method has advantages and disadvantages, but irrespective of what method you use, there are some overarching principles that should guide your smart tag deployment. These best practices should also be placed in the context of overall best practices for network and application management.

Test Your Installation and Updates

Even if you have tested your smart tag thoroughly, it will need to be correctly installed and configured on the client workstation. In software development, deployment is often overlooked. Furthermore, testing an installation is usually omitted. Most developers are so pleased to be done with the project that they are eager to get it packaged and out the door.

Indeed, many implementations are compromised because the installation is not tested. The same can be said for update mechanisms. You should take the time to test your installation and update mechanisms on test machines that accurately reflect the diversity you encounter in your enterprise. If you are using multiple styles of installation and updating, try each of them more than once and make sure that they will work. Try to simulate the real-world setting as closely as possible.

When you are sure that the installation or update is working properly, try it on a sample of your users before broadcasting to the whole enterprise that the rollout has begun. This way, if you encounter problems you can deal with a smaller group making it easier to fix problems. It will also help in retaining the credibility of your application if the bulk of users experience it at its best.

Consider Aptitude

When thinking about how to distribute your smart tag application, think about the level of training and knowledge possessed by the end-users and the IT support staff. Users with minimal application knowledge should not try to install your applications. Set up policies on your network, if needed, to prohibit users from installing applications without the appropriate permissions.

With respect to IT support staff, you want to come up with a distribution mechanism that will be easy to troubleshoot and support. If the support staff is small or is under-trained, you need to minimize the impact on the rest of the applications being used. Also, make sure that those charged with support are sufficiently educated in how smart tags work, how they relate to Office XP, and exactly how they are being installed. If there are questions or problems with your custom smart tag and the support personnel are unprepared, user confidence in your applications and in the technology generally will erode.

Look at the Big Picture

When rolling out your custom smart tags, think about how this initiative fits in the larger context of what is going on in the enterprise. If the users are just getting used to their operating system upgrade as well as a new line-of-business application, it may not be a good time to throw new technologies at them. You may want to roll out your smart tags to smaller groups and deliver the new technologies incrementally.

The "big picture" also includes the adoption of Office XP itself. If your enterprise is piloting installations of Office XP, this is probably a good time to try out some implementations of smart tags because the groups are small and manageable. You can try out different methods of installing and updating the smart tags and get feedback from users and support staff about how they felt about the technology.

Gather Information

As you rollout your custom smart tag, keep detailed logs of failures and discovered solutions to problems you encounter. Never let the same failure occur more than once. To aid you, retain historical information that will be helpful to support the investment you have made in smart tags. It is also a good idea to keep a copy of your installation packages, scripts, other files, and documentation in a central location that is easy for all concerned to use and access.

Part of the learning you do should lead to standardization. You should develop standards for the way smart tags are developed and how they are deployed. You may want to create a template Installer project that can be used by all developers who will make smart tags. This will help ensure that they are deployed in a similar way depending on circumstances.

Update Mechanisms

Once you have a smart tag DLL installed, it is unlikely that it will never require changes. In fact, if you are designing your smart tags properly, you will be designing them to be tightly integrated with your users' needs and business requirements. As they change, so will your smart tag need to adapt. That said, a well-designed application is one that possesses a range of flexibility allowing it to adapt to business alterations without needing to be completely redeployed. But that range of adaptability will eventually be exhausted, and you will find yourself needing to change a smart tag DLL and then propagate that change to client workstations.

Microsoft Systems Management Server

One of the most intelligent ways to manage the updates to any COM DLL is to use a management tool like SMS. With SMS you can query the client workstation and find out which version of the target application is installed. You can close any applications that depend on the smart tag DLL in question, find out which version is installed and proceed with the installation if necessary. Using SMS also allows you to write programs that can gracefully recover from problems during the installation and troubleshoot at that time. You can also get reports from SMS that inform you as to what has occurred during installations and updates on various workstations. The principal benefit to using SMS is that it does not require any end-user involvement nor does it require going to each workstation and manually doing the update for the end-user.

Windows Installer

You can still use an .msi file to update the installation of a smart tag. The package can check which version is currently installed and then complete the update. You can configure the .msi program to make sure that none of the applications that depend on the smart tag are currently running and prompt the user to close them before continuing. Keep in mind that this same .msi file can be used from an administrative installation point or within another program. Unlike the initial deployment, you cannot use the .msi file with the Custom Installation Wizard or the Maintenance Wizard to modify the settings to existing programs that are external to Office, like your smart tag DLLs. The Maintenance Wizard is used to change settings to Office itself and cannot affect those programs that were part of a chained installation.

Internet Download

Another way to deploy a custom smart tag DLL is to create an Internet download. Using this technique is convenient, because users can be informed that they need to navigate to a Web page with an ActiveX control, most likely the same one they used when initially installing the smart tag application. ActiveX controls have a version number, and you can create a new version of the ActiveX control for the smart tag installation that uses your updated .msi file to modify the smart tag DLL. When the user navigates to the Web page, the new ActiveX control will automatically be downloaded and the new .msi program will run and install your updated smart tag application. You could also use this as an opportunity to install a new smart tag DLL.

MOSTL

Fortunately, the Microsoft Office Smart Tag List Tool infrastructure already has an update mechanism. This is carefully documented in the Smart Tag SDK. In summary, the smart tag list file has settings that specify a URL, which the smart tag will access when checking whether an update is required or not. In addition, there are settings for the frequency of these checks and a value that indicates the last time an update occurred. The URL references an Active Server Page that points to an XML file. If the list file requires updating, the Active Server Page retrieves the XML file and places it on the client workstation, effectively replacing the old XML list file.

In order for this technique to be successful, you need to have a highly available and reliable Web server. You should also avoid using large list files. Some developers may attempt to create list files of several megabytes or more and then roll this out in an enterprise setting. Any time a list file grows to this magnitude it is a signal of inappropriate use of the MOSTL files and should prompt the consideration of creating a custom smart tag DLL. One way to compress list files is to use the maketrie.exe utility, a command line application that takes plain text files and converts them to .bin files that can still be understood by the MOFL.DLL. Compressing the file will give you better transfer speeds and take up less space on the client workstation. Using the compressed files will allow you to scale from 5,000 terms with XML to up to 100,000 recognition terms in a .bin file because the term list, after being processed by maketrie.exe (see Figure 2), is completely indexed and made more easily searched by the smart tag recognizer. Another benefit is the fact that you will not be transferring plain text across your network or storing it on local machines, thus allowing you to hide details of the files from potential tampering.

Using maketrie.exe can yield dramatic results, compressing files up to 75 percent. For example, in testing, a term list file containing approximately 100,000 terms is about 1 MB in size. After using the maketrie.exe utility, this same term list is about 300 KB in size. To grasp the impact on network resources, consider an organization with 50,000 workstations. Assume that each day, all of the workstations download an update to just one term list in plain XML that is 1MB in size. In this scenario, each day, 48 GB of data will be downloaded to client workstations. By reducing this amount by 700 KB per transfer, the total amount of transferred data each day would be reduced by 34 GB.

Figure 2. Output reported to the command window after running maketrie.exe (click image to see larger picture)

Most problems you will have in using the auto-update feature of MOSTL files have to do with the values relating to the update frequency and checkpoints.

Conclusion

The purpose of this paper is to describe techniques for deploying smart tags in an enterprise. An enterprise usually means that there are many workstations, many users, and a potentially diverse network infrastructure and varied application standards. There may be thousands of workstations with differing versions of software installed. The last thing you want to do with smart tags is contribute to possible confusion or overwhelm administrators and support staff. You should devise the most sensible strategy given the training and knowledge of users, the preparation of support staff, and resources available in the enterprise. Also, keep in mind that the initial deployment of your smart tag is only the part of its overall lifecycle. Inevitably, it will need to be maintained, repaired, updated, and potentially removed. By planning the development, deployment, and maintenance of your smart tag solution it is more likely that users in your enterprise will embrace the technology and lead to future successes.

About the Author

John R. Durant independently specializes in collaboration and Web technologies. He provides technical and project leadership, authorship, and speaking services. He earned a Bachelor of Arts degree and a Master of Arts degree at Brigham Young University, and a Master of Arts degree at the University of Minnesota. He is a Microsoft Certified Solution Developer, Microsoft Certified Systems Engineer, Microsoft Certified Database Administrator, and a Microsoft Certified trainer. Readers may reach John at jrd@architechsIT.com.

For Further Information

For more product information, see the Microsoft Office Web site.

For more technical information, see the Microsoft Office Developer Center.