How to switch from Apache Velocity macros to Groovy

Apache Velocity macros will stop working when XTRF 10.0 comes out. Follow these steps to make sure all your macros stay functional after that.

Apache Velocity had been deprecated back in XTRF 8.9, and from that point on, Groovy has become the only supported scripting language for macros in XTRF. Additionally, from XTRF 9.4 on, adding new Velocity macros has been disabled, but existing ones are still functional. This will change with the premiere of XTRF 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.

1. Find existing Apache Velocity macros

Go to the Configuration Menu > Integration > XTRF Macros.

In the ‘Filter’ window, on the left side of your browsing view, select Apache Velocity from the ‘Script Language’ list, and click Search.

Alternatively, on the macros list itself, you can go to the ‘Script Language’ column, and click on sorting arrows to order the items, and display Apache Velocity macros on top of the list.

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 instructions below. Velocity macros will be marked on the list with as (deprecated).

Note

If your browsing view has been altered, and you can’t see the ‘Script Language” filter and column, go to the top-right of your item list, click on the View: view name drop-down menu, and Edit your view.

2. Check the purpose of your Velocity macros

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.

Click on the macro to view it. Inspect the ‘Class Name’ and ‘Name’ to learn what the function of the macro is. 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.

See if the Macro Modifies Model Data box is checked. If it is, then running this macro would alter existing information in XTRF.

See if the Macro Generates Output box is checked. If it is, then running this macro would result in generating additional information, like reports, but not alter existing information in XTRF.

Scroll down to the ‘Permissions’ section and see who the macro is shared with.

Performing these steps may 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.

3. Check Periodic Jobs for macros

Some Periodic Jobs use macros. If the macros are written in Apache Velocity, the Periodic Jobs will stop working after the release of XTRF 10.0, so they need to be checked as well.

Go to the Configuration menu > Integration > Periodic Jobs.

In the text bar of the ‘Filter’ window type in macro and click Search. The result will reveal all existing ‘Macro subscription’ Periodic Jobs. If the macro is active and written in Apache Velocity, it will be marked on the list with a warning icon. However, even non-active Periodic Jobs should be checked if they include macros written in Apache Velocity.

Note

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

4. Rewrite existing Velocity macros in Groovy

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

Do it yourself or contact a person proficient in scripting to recreate the macros in another language. XTRF has prepared a simplified user guide for writing in Groovy to help with that. You can read it in THIS ARTICLE.

Alternatively, you may ask XTRF for help. Contact XTRF Helpdesk or your Customer Success Manager. Additional fees may apply.

5. Relink Periodic Jobs to newly created Groovy macros

If you were using ‘Macro subscription’ Periodic Jobs linked to macros written in Apache Velocity, click to Edit them. Then click on the Macro drop-down menu, select the newly created macro written in Groovy, and click Save. That way Periodic Jobs will remain functional after the XTRF 10.0 release.