Understanding Fully Trusted Forms [InfoPath 2003 SDK Documentation]

Applies to:

Microsoft Office InfoPath 2003

Microsoft Office InfoPath 2003 Service Pack 1

Microsoft Office InfoPath provides the ability to create fully trusted forms, which are forms that have greater security permissions and are allowed to access system resources and other components on a user's computer. This article explains what a fully trusted form is and why it is used and describes how to convert a standard form into a fully trusted form, either manually or by using the form registration tool.

Introduction
Why Use a Fully Trusted Form?
What Makes a Form Fully Trusted?
Creating a Fully Trusted Form
Deploying a Fully Trusted Form
Installing a Fully Trusted Form
Removing a Fully Trusted Form
Using a Fully Trusted Form
Making Changes to a Fully Trusted Form
Conclusion

Introduction

Microsoft Office InfoPath forms can be deployed with varying levels of security, and the level you use is dictated by the level of access to external resources that you want a form to have. By default, InfoPath forms are restricted from accessing system resources and are not allowed to use any software components that are not marked as safe for scripting. However, this behavior can be overridden so that a form can access system resources and other external resources, including software components that are not marked as safe for scripting.

For a form to be used, InfoPath must be able to access the form template that the form is based on. When you create a form template, InfoPath creates an entry in the form definition (.xsf) file that contains the URL of the location of the form template. A URL-based form is said to be sandboxed: When a user fills it out, the form is placed in a local cache and denied access to system resources. This type of form inherits its permissions from the domain in which it is opened.

However, you can modify a form so that it is based on a Uniform Resource Name (URN) instead, allowing access to system resources. Forms of this type are said to be fully trusted.

Note  Because fully trusted forms are located on the Custom Installed Forms tab (in the Forms dialog box) on users' computers, users may refer to fully trusted forms as custom installed forms.

Why Use a Fully Trusted Form?

Fully trusted forms have a higher set of permissions than sandboxed forms. For example, they can contain programming code that uses external objects for accessing system resources, they can use software components or Microsoft ActiveX controls that are not marked as safe for scripting, and they can use custom business logic provided by Component Object Model (COM) components.

In addition, some members of the InfoPath object model are set to security level 3, which means that they can only be used in a fully trusted form. For example, to access the Microsoft Office CommandBars object, you use the CommandBars property of the InfoPath Window object to set a reference to it. Because this property is set to security level 3, it cannot be used in a form that is not fully trusted.

Note  Using the CommandBars property of the Window object, or any other object model member that has a security level of 3, in a form that is not fully trusted will result in a "permission denied" error.

What Makes a Form Fully Trusted?

The following actions, involving both the InfoPath user interface and the form files, are required to create and use a fully trusted form:

• Enabling InfoPath to allow for the use of fully trusted forms on the General tab in the Options dialog box. If this option is not enabled, users will not be able to open fully trusted forms.
• Modifying the form so that it is URN-based, rather than URL-based.
• Adding the requireFullTrust attribute to the .xsf file and setting its value to Yes.
• Registering the fully trusted form on the target computer by using the RegisterSolution method of the InfoPath ExternalApplication object.

Note  You can create a URN-based form that is not fully trusted by setting the requireFullTrust attribute to No. This type of form will have access to system and cross-domain resources, but users will be prompted to allow it.

Creating a Fully Trusted Form

There are two methods for creating a fully trusted form: you can create the form manually, which involves modifying some of the form files directly, or you can use the InfoPath form registration tool.

Manually Creating a Fully Trusted Form

To manually create a fully trusted form, follow these steps:

1. Make a backup copy of the form template that you want to make fully trusted.

2. Open the form template in InfoPath design mode.

3. Decompress the form files to a folder on your hard disk by clicking Extract Form Files on the File menu, and then close InfoPath.

4. In the folder that you extracted the form files to, open the form definition (.xsf) file (named manifest.xsf by default) in a text editor such as Microsoft Notepad.

5. Add the following attributes to the xDocumentClass element in the .xsf file:

   requireFullTrust="yes"
   name="urn:MyForm:MyCompany"
   

   Note  The values used for the URN can be any type of string value, as long as this value is unique. There must be at least two values after the urn: prefix, and these values must be separated by a colon. In addition, the URN should be no longer than 255 characters.

6. Save and close the .xsf file, and then open the XML template (.xml) file (named Template.xml by default) in a text editor such as Notepad.

7. Remove the href attribute from the mso-infoPathSolution processing instruction and replace it with the same name attribute you used in step 5 for the .xsf file.

   Note  The URN values used for the name attribute must be the same in both the .xsf file and XML template file.

8. Save and close the XML template file.

9. Repackage the files into the .xsn CAB format with a tool such as makecab.exe.

   Note  Although InfoPath design mode supports repackaging the form files into an .xsn file, doing so will revert the form to a URL-based form. For this reason, you must repackage the files manually to avoid overwriting your changes to the form files.

10. Create a custom installation program by using the RegisterSolution method of the InfoPath ExternalApplication object to install the fully trusted form. A simple way to do this is to create a script file with the following lines of code (in Microsoft JScript syntax):

    objIPExtApp = new ActiveXObject("InfoPath.ExternalApplication");
    objIPExtApp.RegisterSolution("C:\\MyForms\\MyTrustedForm.xsn");
    objIPExtApp.Quit();
    objIPExtApp = null;
    

    Note  Although this example uses a simple script file, you can also use a more robust installation mechanism such as Microsoft Windows Installer (.msi) files. Be sure, however, to use the RegisterSolution method to properly install the fully trusted form on the target computer.

    If you need to remove a fully trusted form, you can use the UnregisterSolution method of the ExternalApplication object.

Using the RegForm Tool to Create a Fully Trusted Form

Although you can convert a standard form to a fully trusted form manually, as described in the previous section, this can be tedious and complicated. To simplify the conversion, InfoPath provides a form registration tool called RegForm that simplifies the process. This tool is a command-line utility program with features that allow you to:

• Automatically make a backup copy of the form template
• Make the necessary changes to the .xsf file and XML template file to make the form fully trusted
• Update the version number of the form template
• Package the files in the .xsn CAB file format
• Create a custom installation program for installing the fully trusted form

To use the RegForm tool, follow these steps:

1. Click Start, and then click Run.

2. In the Open box, type cmd and click OK.

3. Navigate to the folder that contains the RegForm tool.

4. Enter the following at the command prompt:

   RegForm /U urn:MyForm:MyCompany /T Yes C:\MyForms\MyTrustedForm.xsn
   

In this example, replace the values for the /U switch and the name of the form template file with your own requirements and file location. The /U option provides the URN, the /T option indicates that the form should be marked as a fully trusted form, and the last parameter is the file and path name of the form template that is to be converted.

When the tool completes its processing, you will see that it created a .js file and a .bak file in the same folder that contains the form template that you are converting. The .bak file is a copy of the original form template file before the fully trusted changes were made to it; the .js file is a script file that can be used to install the fully trusted form.

In addition to creating a .js file for installing a fully trusted form, the RegForm tool supports creating an .msi file if you have Microsoft Visual Studio .NET installed. To create an .msi file, use the /MSI option, as shown in the following example:

RegForm /U urn:MyForm:MyCompany /T Yes /MSI C:\MyForms\MyTrustedForm.xsn

In this example, replace the values for the /U switch and the name of the form template file with your own requirements and file location.

When the tool completes its processing, you will see that it created an .msi file in the same folder that contains the form template that you are converting.

Note  If you use the /MSI switch but do not have Visual Studio .NET installed, the RegForm tool will create the default .js file for installing the fully trusted form. The RegForm tool also creates a Visual Studio .NET setup project in the %temp%\RegForm directory. You can use this project to modify the MSI installation routine to fit your requirements.

Other options can be used with the RegForm tool to provide more control over the values that it uses, such as the form template name, company name, and version number. To learn how to use these and other options, use the /? switch to view the RegForm tool command-line Help, as shown here:

RegForm /?

Deploying a Fully Trusted Form

How you deploy a fully trusted form depends on the type of installation routine that you create. If you use a script file for the installation routine, you will need to send the user both the script file and the form template (.xsn) file for the fully trusted form. The script will register the fully trusted form based on its folder location, so you must be sure that the script uses the correct folder name.

If you use an MSI installation routine, you only need to distribute the .msi file. The MSI installation routine will contain the form template file and will automatically take care of registering the fully trusted form from the folder in which it is installed.

Installing a Fully Trusted Form

The user's experience when installing a fully trusted form is determined by the type of installation routine that you create. The types of installation routines that can be used to install a fully trusted form include a simple script file that you create, a script file created by the RegForm tool, and an .msi file created by the RegForm tool.

Simple Script File

If you use a simple script file to call the RegisterSolution method of the ExternalApplication object, the user will only see InfoPath being opened. This is because the call to the RegisterSolution object causes InfoPath to be opened, but does not cause a form to be opened.

Note  In this case, you can add custom alerts to your scripting code to notify the user when the installation is complete; however, the RegForm tool will do this for you automatically.

RegForm-Generated Script File

If you use the RegForm tool to create a .js file for installing a fully trusted form, a dialog box asks the user to confirm whether he or she wants to register the fully trusted form, as shown in Figure 1.

Figure 1. Registration confirmation

A second dialog box confirms that the registration is taking place, as shown in Figure 2.

Figure 2. Registration status confirmation

A final dialog box confirms that the registration was completed, as shown in Figure 3.

Figure 3. Successful registration confirmation

Note  InfoPath opens during the registration process, but it automatically closes when the registration is complete.

RegForm-Generated .msi File

If you use the RegForm tool to create an .msi file for installing a fully trusted form, a wizard guides the user through the installation process. The first page of the wizard is shown in Figure 4.

Figure 4. First page of the setup wizard

Clicking Next opens a folder selection page, as shown in Figure 5.

Figure 5. Folder selection page

Note that the default installation location for the fully trusted form is <drive>:\Program Files\InfoPath Form Templates\.

After clicking Next, the user is prompted to confirm installation of the fully trusted form. When the installation is complete, a completion confirmation page appears, as shown in Figure 6.

Figure 6. Successful installation confirmation

Note  InfoPath opens during the registration process, but it automatically closes when the registration is complete.

Removing a Fully Trusted Form

As with installation of a fully trusted form, the process for removing a fully trusted form can vary depending on the type of installation that you used. In general, the process for removing includes the following:

• Calling the UnregisterSolution method of the InfoPath ExternalApplication object
• Removing the fully trusted form from the user's hard disk

Simple Script File

If you want to use a simple script file to remove a fully trusted form, the following lines of code (in JScript syntax) can be used:

objIPExtApp = new ActiveXObject("InfoPath.ExternalApplication");
objIPExtApp.UnregisterSolution("C:\\MyForms\\MyTrustedForm.xsn");
objIPExtApp.Quit();
objIPExtApp = null;

RegForm-Generated Script File

If you want to use the .js script file that the RegForm tool generates to remove a fully trusted form, you can do so on the command line, as shown here:

MyTrustedForm /uninstall

By default, the name of the .js file is the name of the form template.

Note  Several other command-line options can be used with the .js file that the RegForm tool generates. To see an explanation of these options, use the /? switch on the command line to view Help for the .js installation file, as shown here: MyTrustedForm /?

RegForm-Generated .msi File

If you want to use the .msi file that the RegForm tool generates to remove a fully trusted form, you can do so by double-clicking the .msi file to open it. If the fully trusted form that the .msi file installs is already registered on the system, the wizard shown in Figure 7 will start.

Figure 7. First page of wizard for .msi repair or removal

If you click RemoveFormName and then click Finish, the fully trusted form will be unregistered and removed from the user's hard disk.

Users can also perform a more generic removal of the fully trusted form by using the Add or Remove Programs dialog box that can be opened from Control Panel. In this case, they select the fully trusted form name in the list of Currently installed programs and then click Remove.

Using a Fully Trusted Form

Using a fully trusted form is very similar to using a standard form. The only significant differences are that the form can access restricted resources and warnings will no longer be displayed.

Note  To enable InfoPath to use a fully trusted form, users must ensure that the Allow forms that I install with a custom setup program to have access to files and settings on my computer check box is selected under Security options on the General tab in the Options dialog box. (To open the Options dialog box, click Options on the Tools menu.)

A fully trusted form can be opened in InfoPath from the Custom Installed Forms tab in the Forms dialog box, as shown in Figure 8.

Figure 8. The Custom Installed Forms tab

The Forms dialog box opens when you click More Forms in the Fill Out a Form task pane.

Making Changes to a Fully Trusted Form

Making changes to a fully trusted form can be a bit tricky, depending on whether you are making changes to the form template (.xsn) file or to the extracted form files. If you are only making changes to the .xsn file, you can simply have your users replace their existing .xsn file with the new one after the changes are made. They will not need to reinstall it by using a custom installation program.

However, if you are making changes to the form files that the .xsn file contains, you will need to repackage the files, as explained earlier, and then have users reinstall the fully trusted form.

Note  The best approach is to save the form template back to the .xsn format from InfoPath design mode, and then use the RegForm tool to convert the form template to a fully trusted form.

Conclusion

Depending on your business requirements and the needs of your users, you may need to create a form that has a higher set of permissions than the standard InfoPath form. InfoPath provides the ability to modify a form so that it can access system resources and other external resources that are not marked as safe for scripting. This can be done manually by making modifications to the form files that a form template contains, or it can be done by using the InfoPath RegForm tool.