Share via

Using Macros in the Groove Forms and InfoPath Forms Tools

  • Article

Macros are scripts that are explicitly executed by a user that is a member of the workspace. Macros perform automated tasks on a set of records. Macros can automate bulk tasks that would be inconvenient for the user to perform on many individual records. A user invokes a macro by selecting it from the Run Macro menu. Each Forms tool can have one special macro, called the Paste Macro, that is automatically invoked whenever a user pastes records into the Forms tool.

Macros are similar to form scripts in that they are executed once for each record, but unlike form scripts, there is no form present when the macro is executed. Consequently, there are no user events, you cannot use DOM programming, and there are no system events.

The record is provided to the macro in a parameter rather than through the GetFormRecord() global function, which is used in form scripts. Most of the global functions are not usable in a macro. The global functions that are callable from macros are noted in the function descriptions. In addition, you do not need to call GetApp() function since the equivalent Forms Tool UI Delegate is provided to the macro in the i_FormsToolUIDelegate parameter.

When a user executes a macro on multiple records, the updates are treated as a block for success or failure. Groove does this by opening a transaction before the macro starts on the first record and committing the transaction after the macro completes for the last record in the set. If your macro script code can encounter an error condition where you want to continue the script, you must use a JavaScript try-catch block to avoid generating the exception. If your macro script generates an exception and does not catch it, Groove cancels the entire transaction and no records are changed by the macro.

Since a macro is executed within a transaction, you must not call any method or function that displays a modal dialog. See the section on Transactions for an explanation of this restriction and a list of these methods and functions.

Although the macro can operate on a record, there is no active form while the macro is running. Consequently, you cannot call any method or function that references the current form in a macro. The following methods reference the current form and should not be called from a macro:

  • GrooveFormsToolUIDelegate

    • AppendLinksToRichTextField

    • SaveCurrentFormData

    • NavigateToForm

    • NavigateToView

Most of the Public Script Functions reference the current form and should not be called from a macro. The following public script functions can be called from a macro:

  • CreateBSTREnumFromArray

  • CreateUniqueID

  • DoesFunctionExist

  • IsValidDate

In a macro, you can perform lookups on a Forms tool that is in the same workspace as the Forms tool containing the macro, but you cannot do cross-space lookups.

When you paste a lookup into a macro, the code will look like:

var ValuesBSTREnum = i_FormsToolUIDelegate.LookupValuesByStringForMacro
    (int_GetLookupStringForObject("f4a...65f84"), 
    i_FormRecord);

Creating a Macro

To create a macro and make it available to the Forms user, you select Create New Macro from the Design Object Pane and then do the following:

  1. Name the macro. This name will appear in the user's Run Macro menu.

  2. Select JavaScript or VBScript for the implementation language.

  3. Select the scope of the macro. When the user runs the macro, it will be run on the scope that you have specified. The scopes available are:

    • All records.

    • All records in view.

    • Selected records.

    • All records that have been created or updated since the last time the macro was run.

    • All unread records.

    • Pasted records. There can be at most one macro with a scope of "Pasted records" in a single Forms tool.

  4. Enter the code for the RunMacro function.

  5. Optionally, add more code in which you can define global variables or functions that are referenced by the RunMacro function.

  6. Optionally, define lookups. After defining a lookup, you select Copy and then Exit. You can then paste the lookup into your macro or into a function defined in the More Code window. When you create a lookup in a macro, you can only perform the lookup in Forms tool within the same workspace as the Forms tool you are developing. You cannot look up data in another workspace from within a macro.

  7. When you have finished entering the code, select Save.

  8. If you want to restrict use of the macro to certain members of the workspace, you should click on the options tab and specify which roles, manager, participant, and guest can use the macro. You can also select individual members of the group; these members will be able to use the macro regardless of their role.

  9. Finally, select Save to Groove to make the macro available to the Forms tool users.

  10. Note that users who run macros must have permissions to perform the actions that the macro specifies.

The macro is called once for each record in the set. Note that global variables are initialized before the first record in the set, and retain their value from one record to the next. The order in which the macro is called for each record in the set is undefined.

If more than one macro uses the same More Code block, you must enter the code separately in each the More Code window for each macro. Macros are unlike scripts, where multiple scripts can reference functions described in one script file. With a macro, you have access only to the items defined in the More Code window for that particular macro.

Defining a Paste Macro

You can define a special Paste macro that is automatically executed when the user pastes a record into the Forms tool. To define the Paste macro, define a new macro and specify that it should be run on "Pasted Records". You can only define one Paste macro for a Forms tool. The Paste macro does not appear in the Run Macro list.

When the user pastes a record, none of the event or system scripts are run. Consequently, if you are using these system scripts to ensure that new or updated records conform to certain rules, you may want to also enforce these rules in a Paste macro.

A pasted record does not get the same field initialization as a new record. For example, if your form includes a read-only text field that has a unique initial value, all new records will be assigned a unique string value in this field, but a pasted record will have the same value as the original record. The following Paste macro ensures that a pasted record gets a new unique string value in the TaskIdentifier field.

function RunMacro (i_FormRecord, i_FormsToolUIDelegate)
{
  i_FormRecord.SetField("TaskIdentifier", CreateUniqueID());
}

See Also

Reference

Public Script Functions

Concepts

Using Scripts in the Groove Forms Tool
Accessing Groove Services
Groove 2007 Forms Concepts