• Groovy scripts are considered a function.

• In Groovy, the very last statement of the function is considered a return value.

• The return value will be the XTRF Macro output.

Declaring and using variables

Groovy 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:

import com.radzisz.xtrf.model.quote.Quote
Quote quote

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.

def hello = "hello world"
hello

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.

Closures

One 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 conditions

Loops in Groovy can be done in two basic ways:

For loop works exactly like in C++, Java, and other programming languages:

for(variable declaration ; expression ; increment){
  //code inside a loop
}

The second way to create a loop is a while loop. Its structure is simpler than the for loop, as it only consists of the condition and the code.

while(expression){
  //code
}

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:

• break, which stops further execution of the loop (even if the condition is true and the loop would normally be executed again):
  

  

• Continue, which skips the rest of the code in the current iteration of the loop only:
  

  

  Please note that if the i variable was not iterated at line 5, the while loop would be endless, as i would remain there without further incrementation!

  The same result using the for loop:

The if used above is the example of checking a condition. The structure is very simple:

if(condition){
  //code
}
else{
  //code
}

The else part is optional: it is run only when the condition specified in the if condition is not met.

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:

Preparing the CSV

CSV 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 Tuple class from the Groovy API is a good idea to use here. A tuple is like a list: it has a stated number of elements, and so does a CSV file, i.e., if there are four headers, each line needs to have four elements.

Our CSV file will have three columns:

• Name

• Email

• Tax Number

Let's set our separator as a semicolon and type out the header.

import com.radzisz.xtrf.utils.velocity.VelocityTagUtils
import com.radzisz.xtrf.model.partner.customer.Customer

class ExportClientsMacro {
  def list
  def params    
  VelocityTagUtils utils = new VelocityTagUtils()
    
  ExportClientsMacro(list, params) {
  this.list = list
  this.params = params
  }

  def runMacro() {
    String separator = ";"
    Tuple header = ["Name", "Email", "Tax Number"]
    List<Tuple> lines = []
    return 0
  }
}
new ExportClientsMacro(list, params) .runMacro()

We've also created a list of lines we will start filling out in the next step.

Getting the data and filling the lines

You know that the list variable contains the list of Customers.

We will be iterating over the list and filling one line at a time; for this, the each method will be the best choice.

def runMacro() {
    String separator = ";"
    Tuple header = ["Name", "Email", "Tax Number"]
    List<Tuple> lines = []
    list.each { Customer customer ->
    }
    return 0
  }

In the Customer class, there are get() methods for getting all of the required fields.

Here's the method to get the full name:

Let's get all these fields and assign them to variables inside the each closure.

Now that we have the data, let's put it in a Tuple3 (size of 3 - tuples have their size included in their class name) and add it to the list.

def runMacro() {
    String separator = ";"
    Tuple header = ["Name", "Email", "Tax Number"]
    List<Tuple> lines = []
    list.each { Customer customer -> 
      String name = customer.getFullname()
      String email = customer.getEmail()
      String taxNumber = customer.getTaxNo1()
      Tuple line = [name, email, taxNumber]
      lines.add(line)
    }
    return 0
  }

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 createCsv. It will return a String that will be the final product of the macro, and it will take the header, the list of lines, and the separator as parameters.

static String createCsv(Tuple header, List<Tuple> lines, String separator) {
  String preparedHeader = header.join(separator)
  String preparedLines = lines.collect { it.join(separator) }.join("\n")
  return preparedHeader + "\n" + preparedLines
}

Here, we use the join method to transform lists into strings, which now fit the .csv format since they are separated with semicolons.

For the lines - we use the collect method, which transforms each entry (here, we transformed each line tuple to join it with semicolons), and then we use the join method again to separate the lines with the newline sign.

We can now use this method to get the return value of the macro.

def runMacro() {
    String separator = ";"
    Tuple header = ["Name", "Email", "Tax Number"]
    List<Tuple> lines = []
    list.each { Customer customer -> 
     String name = customer.getFullname()
      String email = customer.getEmail()
      String taxNumber = customer.getTaxNo1()
      Tuple line = [name, email, taxNumber]
      lines.add(line)
    }
    return createCsv(header, lines, separator)
}
static String createCsv(Tuple header, List<Tuple> lines, String separator) {
  String preparedHeader = header.join(separator)
  String preparedLines = lines.collect { it.join(separator) }.join("\n")
  return preparedHeader + "\n" + preparedLines
}

Now paste the entire code into the macro editor in XTRF and start testing!

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 getTasks() method on the Project class.

import com.radzisz.xtrf.model.project.Task

def runMacro() {
  list.each { Project project ->
    project.getTasks(). each { Task task ->
    }
  }
  return 0
}

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.

import com.radzisz.xtrf.model.project.Project
import com.radzisz.xtrf.model.project.Task

def runMacro() {
  List<String> output = []
  list.each { Project project ->
    project.getTasks(). each { Task task ->
      Date tomorrow = new org.joda.time.LocalDateTime().now().plusDays(days: 1).toDate()
      task.getDateBoundaries().setDeadline(tomorrow)
      output.add("Set deadline to ${tomorrow} for task with id ${task.idNumber}")
    }
  }
  return output.join("\n")
}

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.