Accessing Forms Records

You can access the underlying Forms tool record from scripts and macros. In scripts, the GetFormRecord()Public Script Functions provides access to the record underlying the current form. In macros, the****i_FormRecord parameter provides access to the record. Direct access to the record gives you to access all fields in the record by name. In addition, you can access the parent record and child records.

Access to the record is provided by the IGrooveFormsToolRecord Interface interface.

Using Transactions

If you are accessing the record in a form script, you should call the IGrooveFormsToolUIDelegateOpenTransaction Method method to ensure that your script can access the record. A transaction is the Groove mechanism to lock local access to the data in the workspace. Locking the workspace prevents any data from being added, updated, or deleted while you are accessing it. If your script was accessing a record and did not open a transaction, and another user in the workspace deleted the record, your script could get an error. Note that the scope of a transaction is limited to the user's local copy of the workspace. A transaction does not stop another user from updating the workspace; it only defers your workspace getting the updates. Note that all Forms tool transactions are write transactions.

Note

When you have a transaction open, you should not call any method that displays a modal dialog that requires user input. If a script calls a modal dialog when a transaction is open, the user may encounter serious errors, including deadlocks, script errors, exceptions, and data corruption.

The following methods and functions that open a modal dialog and should not be called when you have a transaction open:

• IGrooveFormsToolContactServices Interface

  • DisplayContactProperties Method

• IGrooveFormsToolMessagingServices Interface

  • DisplaySendInstantMessageDialog Method

  • DisplaySendInvitationDialog Method

  • SendInvitation Method

• IGrooveFormsToolUIDelegate Interface

  • DisplayDatePickerDialog Method

  • DisplayError Method

  • DisplayOKMessageBox Method

  • DisplayTextInputDialog Method

  • LaunchOrNavigateToURL Method with a non-Groove URL, such as an http: or mailto: URL.

  • SendInstantMessage Method

  • SendInstantMessageWithLinks Method

• Public Script Functions

  • LoadAddAttachmentDialog

Accessing a Record

The IGrooveFormsToolRecordb36b9724-a448-4489-aa71-d8fc625192e6 interface provides access to the record in the form with the following methods and read-only properties:

• HasField Method—method that returns a TRUE value if the record contains a field with the specified name; otherwise returns FALSE.

• OpenField Method—method that returns as a variant the value of the field with the specified name.

• SetField Method—method that sets the specified field to the specified value.

• HasParentRecord Property—property that returns TRUE if the record has a parent record; otherwise returns FALSE.

• OpenParentRecord Method—method that returns the parent record.

• HasDescendantRecords Property—property that returns a TRUE value if the record has one or more descendant records.

• CreateDescendantRecordEnum Method—method that creates an enumeration of all descendant records.

• Reparent Method—method that makes the record a descendant of the record specified by the ID.

• IsUnread Property—property that returns TRUE if the record is unread and FALSE if it is read.

• MarkRead Method and MarkUnread Method—methods that mark the record as either read or unread.

• ID Read-Only Property—property that returns the record ID.

In addition to the fields defined by the designer and the system fields displayed in the Forms designer, there are the following special system fields that are stored in the record but not available to display or update through the user interface:

• _RecordID—stores the ID of the record.

• _ParentID—identifies the parent record, if it exists. You cannot update this field, but you can change the parent of a record by calling the Reparent method.

• Forms_Tool_grooveFormID—identifies the form associated with the record.

• _IgnoreUnread—if this is set to TRUE in a record, it suppresses Unread notification for the record. This field can only be set from scripts or macros.

Note that a user can still see these fields, and any others, by right-clicking and viewing the record properties.

A script or macro can use the value in Forms_Tool_grooveFormID in a call to the OpenFormIDByAlias method to find the name of the record's form.

Groove Forms Tool Designer Types and Record Data Types

When a form designer creates a new field, they select the field type. The field type determines how the field is displayed on the form and the data type of the field in the underlying record. The following table describes these types.

Designer type	Record field data type	Comments
Text Multi-Line Text Options Buttons Check Box Drop-Down List List Box Password	string	In a List Box, only the selected value is stored in the record. If a List Box has multiple selected values, the values are separated by newline characters in the corresponding field of the record. An exception is that the in the _Readers and _Editors fields, member URLs are stored in the record field, and they are separated by semicolons. The string stored for the Option Buttons and Check Box types is the stored string specified by the forms designer.
Date Date-Time	number	Use the IGrooveFormsToolUIDelegateFormatDate and FormatDateTime methods to convert the number into a date string, and use the ParseDate and ParseDateTime methods to convert a date string to a number.
Number Unformatted Number Currency	number	Use the IGrooveFormsToolUIDelegateFormatNumber method to convert the number into a numeric string, and use the ParseNumber method to convert a numeric string to a number. These methods preserve the precision of the stored number. If you convert a number to a string without full precision, you may alter its value.
Rich Text	object	This data type is a Groove-internal structure. There is no supported mechanism for scripts or macros to access the record data for fields with a Rich Text type.
Attachments	object	This data type is a Groove-internal structure. There is no supported mechanism for scripts or macros to access the record data for fields with an Attachments type.
Contact	IGrooveFormsToolContact	See Using Contacts in Forms for more information.

InfoPath Forms Tool Data Types and Record Data Types

When the form designer creates a new field, they select the field data type. The field data type determines how the field is displayed on the form and the data type of the field in the underlying record. The following table describes these types.

InfoPath data type	Record field data type	Comments
Text Hyperlink	string	Groove treats a hyperlink field as a text field. If you set the value of a hyperlink field with a SetField method, Groove does not ensure that the string is a valid URL.
True/False	string	By default, Boolean InfoPath fields have a value of TRUE or FALSE in the record. If a macro sets the value of the field to another text string, the form will show the field as invalid.
Date Date and Time	number	Use the IGrooveFormsToolUIDelegateFormatNumber method to convert the number into a numeric string, and use the ParseNumber method to convert a numeric string to a number. These methods preserve the precision of the stored number. If you convert a number to a string without full precision, you may alter its value.
Decimal	number	Use the IGrooveFormsToolUIDelegateFormatNumber method to convert the number into a numeric string, and use the ParseNumber method to convert a numeric string to a number. These methods preserve the precision of the stored number. If you convert a number to a string without full precision, you may alter its value.
Whole Number	number	Note that Groove stores the value as a double in the record. If you update the value of the field in a macro, the InfoPath Forms tool converts it to an integer before displaying it in the form.
Rich Text Time	none	There is no record data type that is compatible with these InfoPath data types.

See Also

Concepts

Using Scripts in the Groove Forms Tool
Using Macros in the Groove Forms and InfoPath Forms Tools