FAQ - Macros and Scripts

A.: AQdevTeam macros let you automate repetitive operations, such as removal of old items, e-mail distribution, etc. A macro is a set of operations that you select among those from the base list. Each operation is quite elementary: Create Directory, Execute Program, Copy File(s), Check out From VSS, etc. AQdevTeam Client includes Visual Macro Builder that lets you arrange macros' operations visually and specify their parameters via corresponding dialogs. This makes creation of macros very easy. If the operation you need is missing in the base list, you can add the Script operation to your current macro and then write its script code by hand in VBScript, JScript or DelphiScript.

Using macros, you can "program" nearly all operations normally performed via the user interface. AQdevTeam allows you to track different events that occur in the database and to run macros to perform specific actions when an event occurs. For instance, if you are a developer, AQdevTeam can automatically send you an e-mail notification that a new bug report has been added to the database or that a bug has been assigned to you, or that a bug was moved from the status Pending Validation to Opened.

Macros can also be executed at certain points in time: for instance, each Friday at 6.00 pm you may wish to launch a macro that removes unnecessary and outdated items. Macros that are launched at certain time are called jobs. You can schedule jobs at your desire.

Macros can also be executed upon pressing a button, check box or a radio button in the Edit Form or in the Preview Pane.

All macros you create are stored in the AQdevTeam database. However, a macro can be launched either on the client, or on the server side. Client macros are typically used to handle pressing of buttons in the Edit Form or Preview Pane. Server macros are useful for notifications.

To create, modify and remove macros, you must have the Macro Repository panel installed.

A.: Please make sure that you are not using the AQdevTeamCurrentAction, AQdevTeamCurrentStartStatus and AQdevTeamCurrentEndStatus objects in the script because these objects may be undefined in server macros. For instance, if a user changes an item's status on the client computer, the AQdevTeamCurrentStartStatus object cannot be used in the server macro that is linked to the event of the status change, because this object is undefined on the server computer (the object will be defined only if an item's status is being changed on the server computer).

To determine whether a macro is running on the server, use the AQdevTeamManager.IsRunningOnServer property. To determine whether the desired AQdevTeamCurrentxxxx object exists, you can use the BuiltIn.NamespaceExists method.

As a workaround to the reported problem, we recommend that you obtain the start and end statuses and the last executed action from the Audit Trail list of an item and then perform the desired actions using this information.

A.: To obtain such information from script, use the GetHistory method of the ItemRecord object that corresponds to the desired item. This method returns a collection of Audit Trail records. This collection contains HistoryItem objects which correspond to the Audit Trail record (each record in the Audit Trail panel corresponds to a change of an item status). To determine the user who changed the status, use the HistoryItem.User property.

A.: AQdevTeamCurrentItem provides a program interface to the item, over which AQdevTeam performs an action. For instance, if your macro is run upon changing the Assigned To field of an item, you should use AQdevTeamCurrentItem to get access to the item whose field is changed. Note that AQdevTeamCurrentItem will refer to this item even after the action is done. So, in fact, AQdevTeamCurrentItem provides access to the last modified item in the database.

AQdevTeamCurrentUIItem provides a program interface to the item that is being opened in the Edit Form or Preview Pane at the moment of a macro run. This object is defined only within the macro that is executed as the OnClick event handler of a button on the Edit Form (Preview Pane). If you open several items for editing (that is, if you have several Edit Forms), AQdevTeamCurrentUIItem will correspond to the item that is open in the form in which you clicked the button.

A.: To obtain an item that is currently selected in the Issue Explorer, use IssueExplorerSelection.FocusedItem. If there are multiple items selected, use IssueExplorerSelection.SelectedItems.

If your script belongs to the macro that handles clicks on a button of the Edit Form or Preview Pane, use AQdevTeamCurrentUIItem.

If your script runs in a macro that is executed in response to an event, such as changing of an item field, use AQdevTeamCurrentItem.

(For more information on AQdevTeamCurrentItem and AQdevTeamCurrentUIItem, see the answer to the previous question).

A.: The AQdevTeam help includes the "DelphiScript Description" topic that provides a description of DelphiScript. To find this topic, search for DelphiScript in the index. DelphiScript is very similar to Object Pascal (Delphi), so you can read Delphi's help to learn the statements that can be used in DelphiScript. However, there are some differences between these languages. They are described at http://www.dreamcompany.com/dscriptdesc.html.

As for VBScript and JScript, you can find complete information on these languages in the Microsoft Developer Network library:

A.: When you need to perform a selection of one of several alternatives, like a Yes/No choice, you should use the BuiltIn.AppMessageBox routine. It displays a box with the specified message and buttons.

When you need to get textual data from the user, you should use VBScript’s built-in InputBox method. It displays a dialog with a prompt and a text box.

Similar routines are not available in DelphiScript and JScript, but you can workaround this in the following way.

1. Create a new macro variable in the Variables dialog.
2. Add a VBScript operation that stores user input to the variable. The operation code may look like this:

   [VBScript]
   Sub Main
      VMBVariables.Dlg_Result = InputBox("Enter your name")
   End Sub 

   Dlg_Result stands for the name of the created variable.
3. Open the Operation Properties dialog. In the dialog, assign a unique name to the operation and clear the Enabled property.
4. In your DelphiScript / JScript operation, where user input is required, call the VBScript operation by its unique name and check the user response through the corresponding variable. Here is a code fragment that illustrates this:

   [JScript]
   function Main()
   {
     ...
     VMBOperations.VB_InputBox.Execute();
     ShowMessage('The input was: '+VMBVariables.Dlg_Result);
     ...
   }
   

   VB_InputBox stands for the VBScript operation’s unique name.