Identifying the Forms Tool
The Groove Forms tool is a general purpose tool that can be customized for many purposes. When you are developing a Groove Web Services application, you develop it to work with specific kinds of Forms tools. For example, you may be developing an application that works with the Issue Tracking Forms tool, which is available as a Forms tool template. In such a case, your application must identify which Forms tools are built using that template. If you call the GrooveTools Read operation on a workspace, it identifies which tools are Groove Forms tools and which are InfoPath Forms tools. It also provides the tool name, but does not provide any additional information about the tool. Since workspace members may be able to change the tool name, the tool name is not a reliable mechanism to determine whether a tool was created from a specific template.
The Design Name and Design Version provide a mechanism for Forms Tool designers to document the design of the tool in a way that is accessible to Groove Web Services applications. The Forms tool designer sets the Design Name and Design Version so that developers can identify a Forms tool instance as having a specific design and version. The Design Name is typically specified as a URN. For more information on the format and meaning of the Design Name and Design Version, see the Groove Forms Tool online help.
Note that the Design Name and Design Version document the Forms Tool designer's intent, but do not guarantee that the tool's design is as specified. It is possible for a workspace member, who has design permission, to change a tool's design without updating the Design Name and Design Version. Consequently, your Web Services application should be coded to handle errors that can be caused if the design of the tool is different from the expected design.
The ReadToolProperties operation returns the Design Name and Design Version in the DesignTemplateName and DesignTemplateVersion. In addition, it returns other information about the Forms tool, such as default Form and View ID, URI, and name. It also returns information that impacts Forms users and script developers, such as whether users can create or search records. These settings do not impact whether you can use the CreateRecords or QueryRecords Web Service operations.
The C# code in Example Code: Reading Forms Tool Properties creates a new GrooveForms2 service and tests whether the Tool.Type returned by GrooveTools.Read matches the one associated with the GrooveForms2 service. If the Tool.Type matches, it then tests to see if the Forms tool is designed. Finally, it tests the Design Name and Design Version to see if the instance of the tool was created by the Discussion template provided with Groove 2007.
There is also a version number that is returned in the RecordDataSetSchemaVersionID element whenever you query or read records from the Forms tool. This is an integer value that is automatically maintained by the Forms tool. Whenever the Forms tool design is changed in any way and the sandbox is published, the Forms tool increments this number. If the value of SchemaVersionID has changed, then a record schema may have changed, but it is possible that the Forms designer made user interface changes only and did not change a record schema. Note that when the Forms tool increments the SchemaVersionID it typically increments it by a value greater than 1. The value of the increment is an implementation detail and has no meaning.
In This Section
Example Code: Reading Forms Tool Properties
See Also
Reference
GrooveForms2.ReadToolProperties Operation
Concepts
Accessing Forms Tool Design Information
Testing Whether the Forms Tool Design Has Been Initialized
Getting Information About Forms