XTRF guide to macros
Introduction
Macros are basically long instructions that users can apply to save time on repetitive tasks like long input sequences of keyboard and mouse actions or reusing code. Macros take the form of programming scripts. In XTRF, they're most commonly used to export data, modify custom field values, or alter database entities; however, the possibilities are virtually unlimited.
XTRF uses Apache Groovy as a programming and scripting language for macros. Powerful, optionally typed, and dynamic, it's best compatible with the Java platform with its static-typing and static compilation capabilities, as well as concise, familiar, and easy-to-learn syntax.
For full Groovy macro documentation, click HERE.
Macros settings in XTRF
To manage existing macros and add new ones, go to the Configuration menu > Integration > XTRF Macros.
Check the Enable XTRF Macros box to allow using macros on the XTRF Platform.
Add a macro
To create a new macro, perform the following steps:
Click the Add button on top of the XTRF Macros table.
In the Options section:
From the Class Name drop-down, select the scope of the macro (where it will be applicable, e.g., Project, Job, Vendor Payment, etc.)
Name your macro.
Decide whether it should be Active.
Inactive macros won't appear on the views.For a macro that generates an output file:
Check the Macro Generates Output box.
Provide the Filename with an extension for the generated file, e.g., Output.csv.
Select the file Encoding.
(Optional) From the End of Line drop-down, select the line break type to be used in the output file.
In the Maximum Number of Items field, limit the number of entities for which this macro can be run simultaneously.
Check the Macro Modifies Model Data box if you want the macro to modify data in the system, e.g., change job assignments.
Leave it unchecked if you only want to export data or create reports.
In the Editor section:
(Optional) Click the icon to expand and configure the Editor Options.
Provide the actual code of the macro.
(Optional) Click the icon to preview your output or return value.
Click the Save or Save and Exit button.
Test a macro
To test a macro, perform the following steps:
Open the macro in question in edit mode.
In the Editor section, expand the Editor Options.
In the Test Objects field, start typing the name of the entity on which you want to test the macro.
You can select several test objects.In the Test cases section, click the Add Test Case button. The Add new Test Case pop-up appears.
Name the test case and click the Save button. The test case appears on the list.
Click the icon to run the test case.
If the macro works, you'll get a success flash message. If there are some problems with the macro, the Test Result pop-up window appears.
Limit access to a macro
By default, new macros are available for all user groups (for details about user groups, see the User Groups and Rights article. However, you may want to limit access to certain macros to eliminate the potential risk of errors and system malfunctions. To do so, perform the following steps:
Open the macro in question in edit mode.
Go to the Permissions section.
Uncheck the All Groups box.
Select the groups that will have access to this macro by double-clicking on a group in the Available Items list.
Click the Save or Save and Exit button.
Now the macro can be seen and run only by the selected user groups. Users from excluded user groups won't see the macro on the list and won't be able to run it, even through the API.
User groups with 'Edit' rights to macros can still browse and modify all macros through the configuration menu. This includes changing the permissions to run macros.
Run a macro
Macros can be run from the Smart views corresponding to the macro's classes (Clients, Vendors, Projects, Invoices, etc.).
To run a particular macro, perform the following steps:
Go to the browsing view of the class you want to run the macro for (e.g., Clients module > Clients > All Clients view.).
Check the boxes to select the specific items.
In the menu above the browsing list, click the Macros drop-down menu and select the macro you want to run.
If there are no macros for the desired class on your XTRF platform, the Macros drop-down menu will not appear in this class' browsing view.
Apache Groovy basics
The macro template
This is a universal structure for XTRF macros.
${NAME}
is the custom name of your macro.All the actual code goes into the
runMacro()
method.The variable
utils
contains some useful methods - you can check them out in the Javadoc in VelocityTagUtils.
XTRF macros best practices
These are the rules and templates the XTRF Customization Team sticks to (and we advise you to do so as well to make your coding easier).
The macro code is separated into main parts:
Main macro class
Execution phase
Such a structure is designed for the macro to run automatically whenever started in XTRF (will be run as a standard Groovy script) and to allow testing (by using OO elements).
General rules
Macro must be executed by the
runMacro()
method (without any parameters).Whatever is returned by
runMacro()
is considered the macro output.Every macro class must have a constructor with exactly two parameters: list (the list of processed entities) and params. Names in the class itself can be changed. Those names cannot be changed in the execution line (see below).
The execution line
new GetReceivablesMacro(list, params) .runMacro()
must be present in every macro.
Object Oriented Programming
You can use the benefits of object-oriented programming while writing your macros. You can create as many classes and functions as you need, but be aware that they need to be compiled into a single script before being added to XTRF.
List and Params
You saw two variables defined in the macro template - list
and params
.
List
will be the list of items you run the macro on. If you select three projects from the view and run the macro on them, the list object in that macro will be of the type:List<com.radzisz.xtrf.model.project.Project>
.
You can then iterate over the list in the code of the macro.Params
is for the more advanced users - it is most useful when running a macro from the XTRF Home Portal API. You can execute the Run Macro POST request that contains this JSON:And then, in the macro:
params.id == 848
Will return true.
You can pass a map of as many parameters as you want.
XTRF macro examples
Generate a CSV file
Modify a project