How to switch from Apache Velocity macros to Groovy

Owned by Oksana Vishchuk
Jun 28, 2024
4 min read

Introduction

Apache Velocity macros will stop working starting from v.10.0. Follow these steps to make sure all your macros stay functional after that.

Apache Velocity was deprecated in XTRF v. 8.9, and from that point on, Groovy has become the only supported scripting language for macros in XTRF. Additionally, from XTRF v. 9.4 on, adding new Velocity macros has been disabled, but existing ones are still functional. After an upgrade to XTRF v. 10.0, any existing Velocity macros will stop working.

Let’s make sure that all your macros are written in Groovy before XTRF 10.0.

I. Find existing Apache Velocity macros

  1. Go to the   Configuration menu > Integration > XTRF Macros.

  2. In the Filter pane on the left side, select Apache Velocity from the Script Language dropdown, and click the Search button.
    Alternatively, on the macros list, click the icons at the top of the Script Language column to display Apache Velocity macros at the top of the list.

 

Groovy1.png

 

If the search shows no results - great! It means that all your macros are written in Groovy and will remain functional.

If the search reveals existing Apache Velocity macros, proceed with the instructions below. Velocity macros will be marked on the list as (deprecated).

If your browsing view has been altered, and you can’t see the Script Language filter and column, go to the top-right corner of your item list, click on the View:  dropdown menu, and add the Script Language column or filter to your view. For details, see the Create a new Classic view guide.

II. Check the purpose of your Velocity macros

  1. When in the browsing view, check if Velocity macros are active. If so, they will be marked on the list with a warning icon. Hovering over the icon reveals the warning message that this macro needs to be replaced with one written in Groovy scripting language.

 

Groovy2.png

 

  1. Click on the macro to view it. Check the Class Name and Name fields to learn the function of this macro. There also may be some instructions embedded in the macro expression itself, and you may deduce its purpose even if you’re not proficient in scripting.

  2. Check if the Macro Modifies Model Data checkbox is selected. If so, then running this macro would alter existing information in XTRF.

  3. Check if the Macro Generates Output checkbox is selected. If so, running this macro would generate additional information, like reports, but not alter existing information in XTRF.

 

 

  1. Scroll down to the Permissions section and check with whom this macro is shared.

Performing these steps can help you determine if this particular Velocity macro was actually useful. It may have been created for testing purposes only, or the tasks it used to perform are no longer necessary in your daily operations.

When in doubt, contact a programmer or network administrator in your company, to make sure if having this macro in the future is necessary. If not, you may discard or delete it. If so, proceed with instructions below.

Repeat this procedure with every Velocity macro you have on the list.

III. Check periodic jobs for macros

Some periodic jobs use macros. If those macros are written in Apache Velocity, related periodic jobs will stop working after the upgrade to XTRF v. 10.0, so they need to be checked as well.

  1. Go to the   Configuration menu > Integration > Periodic Jobs. 

  2. In the Filter pane on the left side, type macro in the Name field and click the Search button. This action will reveal all existing Macro subscription periodic jobs. If the used macro is active and written in Apache Velocity, it will be marked on the list with a warning icon. However, we recommend checking even non-active periodic jobs that include macros written in Apache Velocity.

An active periodic job that includes a Velocity macro pretty much guarantees that the macro is used regularly and needs to be replaced with one written in Groovy.

IV. Rewrite existing Velocity macros in Groovy

To stay functional after the release of XTRF v. 10.0, all Apache Velocity macros that are important for your business need to be rewritten in the Groovy scripting language.

You can do it yourself or contact a scripting expert to recreate the macros in another language. XTRF has prepared a simplified user guide for writing in Groovy to help with that (see the XTRF guide to macros).

Alternatively, you can contact XTRF Support for help. Additional fees can apply.

V. Relink periodic jobs to newly created Groovy macros

  1. Go to the   Configuration menu > Integration > Periodic Jobs. 

  2. Locate a Macro subscription periodic job that uses an Apache Velocity macro and click the icon.

  3. From the Macro dropdown list, select the newly created macro written in Groovy.

  4. Click the Save button.

  5. Repeat for other periodic jobs linked to Apache Velocity macros so they remain functional in XTRF v. 10.0