Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Table of Contents |
---|
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.
Info |
---|
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.
Info |
---|
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
Expand | ||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||
Declaring and using variablesGroovy lets the users define their own variables. Variables can be typed (as in Java) or untyped. While typed variables have a predetermined data type, which may disallow certain assignments (e.g., one cannot assign a Date object to a BigDecimal variable), they have one advantage over untyped variables - they allow more control over what and how is processed by the code. Only base Java Classes can be used as typed variables without typing anything else - the rest has to be imported first. For example, to use a Quote class, enter:
The full list of classes used in XTRF can be found in JavaDoc documentation. To declare a variable, simply enter its type (in case of typed variables) or use a special keyword def (untyped variables). After a variable is declared, it can be used by typing its name.
Variables can be used inside a text in quotation marks. The text must be entered in quotation marks to interpret a variable - if the text is entered in apostrophes, variables will not be evaluated. Groovy allows the use of multiline Strings. ClosuresOne of the most powerful tools in Groovy is closures. A closure in Groovy is an open, anonymous block of code that can take arguments, return a value, and be assigned to a variable. Closures are defined by brackets. To call a closure assigned to a variable (named closure in the example above), type its name and parameters. Closure parameters should be put between the parentheses. Parameters are optional - this example closure simply increases the variable by one each time the closure is called. New variables can be defined inside a closure. Those variables will be visible only inside a closure and cannot be used outside of it. Groovy also has some built-in useful closures to run on collections.
Further information on closures can be found at https://groovy-lang.org/closures.html Loops and checking conditionsLoops in Groovy can be done in two basic ways:
The second way to create a loop is a
The while loop will be running as long as the condition set in the expression part is true. This means that if the above example did not have the incrementation of the i variable (i++ in line 5), the loop would run indefinitely! (as 0 is always less than 10). Both loops can also use two control statements:
The
The |
The macro template
This is a universal structure for XTRF macros.
Info |
---|
At the beginning of each macro, you need to import the necessary classes that can be found in the JavaDoc documentation. |
Code Block | ||
---|---|---|
| ||
import com.radzisz.xtrf.utils.velocity.VelocityTagUtils class ${NAME}Macro { def list def params VelocityTagUtils utils = new VelocityTagUtils() ${NAME}Macro(list, params) { this.list = list this.params = params } def runMacro() { return 0 } } new ${NAME}Macro(list, params).runMacro() |
${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:Code Block language groovy { "params": { "id": "848" } }
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
Expand | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||
Let's say that you want to export the clients' details. You want their names (legal name), email addresses, and tax numbers, all in a .csv file. This is how your macro options should look like: The Macro Modifies Model Data box is not checked, as you will not change any of the client's data. Preparing the CSVCSV files are text files that follow a special format: their values are separated by a separator. You want your file to have headers with the names of the fields and then the list of values. We need to create a framework for these elements. You can also use any existing Java framework, but for this simple example, it will not be necessary. The Our CSV file will have three columns:
Let's set our separator as a semicolon and type out the header.
We've also created a list of lines we will start filling out in the next step. Getting the data and filling the linesYou know that the We will be iterating over the list and filling one line at a time; for this, the
In the Customer class, there are Here's the method to get the full name: Let's get all these fields and assign them to variables inside the Now that we have the data, let's put it in a
Now, the macro will do that for each customer in the list, and we will only need to connect the header with the lists and generate the output string. Let's write a method to do just that and call it
Here, we use the For the lines - we use the We can now use this method to get the return value of the macro.
Now paste the entire code into the macro editor in XTRF and start testing! |
Modify a project
Expand | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
In this example, we will change the dates of a project. We want to change all of the tasks' deadlines to tomorrow. Here is the setup:
We will start with the empty template. We know that the list will contain the list of projects selected from the view. We need to get to the tasks, and as projects can have multiple tasks, we need to iterate over projects as well as tasks. For this, we will use the
Then we need to calculate the date we want to change the deadline to and set it. We can also add the information about this task to the output.
For the output, we created a list of strings, which we then joined with newlines so that each log was in a separate line. You can now run the macro on projects, and the output will be displayed. |
Table of Contents | ||
---|---|---|
|