Creating Form Extensions with Velocity

---

While you can easily create reports and widgets for Live Report pages with Velocity, you would usually have to create a Java extension in order to create something that will extend the work item view. But with the „Velocity Form“-extension you will be able to create extensions for the work item view as quickly as for report pages. In this post I’ll show you how to create a form extension that shows the last test result of linked test cases.

Overview

In this post I will go through the following two steps:

1. Download and deploy „Velocity Form“-extension.
2. Create the form extension that shows the last test result of linked test cases.

Download and Deploy the „Velocity Form“ extension

Since Polarion 22R2 the Velocity Form Extension is part of the core product and doesn’t have to be deployed anymore.

In order to create form extensions via Velocity you need the „Velocity Form“-extension first. Otherwise you would have to create them as Java extensions which is in general more effort. (But would also have the advantages that a full blown IDE would bring)

The extension is packaged as part of the „System of Systems Template“. So please go to the extension portal and download the template (it’s free): Polarion Extensions Portal: System of Systems

We just need the „com.polarion.alm.velocityform_1.0.4“:

But you can’t just copy the velocityform_1.0.4 in the extensions folder. You either have to copy the whole SOS_External_Extensions folder in the extensions folder or create the folder structure „com.polarion.alm.velocityform/eclipse/plugins/com.polarion.alm.velocityform_1.0.4“. This is because Polarion searches for the „eclipse/plugins“ folder structure. Otherwise you’ll get the following warning message in the logs (you can find them in [POLARION_HOME/data/logs]:

2022-06-19 11:25:02,039 [main] WARN com.polarion.core.boot.impl.AppLaunchersManager - missing subfolder 'eclipse' under extension directory: E:\Applications\Polarion\polarion\extensions\com.polarion.alm.velocityform_1.0.4

To deploy only the velocity extension you have to:

1. Shut down the Polarion service
2. Create the folder structure „[POLARION_HOME]/polarion/extensions/com.polarion.alm.velocityform/eclipse/plugins“
3. Copy the extension folder into your „[POLARION_HOME]/polarion/extensions/com.polarion.alm.velocityform/eclipse/plugins“ folder.
4. Then delete the „[POLARION_HOME]/data/workspace/.config“ folder (otherwise the extension won’t be loaded).
5. Start the Polarion service again.

Create a Form Extension with Velocity

For this example I’m using the DrivePilot project that is available on every Polarion system. If you don’t have one available, you can create the project by using the „DrivePilot“ template.

In this template we have system requirements linked with system test cases. And I would like to create a form extension for the system requirements, that shows if the last tests were successful.

To create the form extension we have to create a .vm file in the [POLARION_HOME]/scripts folder.

This script will contain the code for the form extension.

To show the form extension in the system requirements we have to adapt the form configuration. Go to Administration > Work Items > Form Configuration > Form Layouts(!) > Edit System Requirement. There we have to add the following configuration to add the form extension:

<extension id="velocity_form" label="Latest Test Results" script="testResultFormExtension.vm"/>

The testResultFormExtension.vm just contained the text „Test“ to check if it works. It should then look like this:

Now we’ll create the form extension with Velocity.

For the start we want to get all linked test cases of the currently opened requirement.

To do this we’ll create a SQL/Lucene query, as this is the most performant way to get certain linked work items as a list (10x+ faster than using velocity and looping trough linked items). The SQL query could look like this:

select
 WORKITEM.C_URI
from
 WORKITEM
 inner join PROJECT on WORKITEM.FK_URI_PROJECT = PROJECT.C_URI
 inner join STRUCT_WORKITEM_LINKEDWORKITEMS LINK on WORKITEM.C_PK = LINK.FK_P_WORKITEM
 inner join WORKITEM REQUIREMENT on LINK.FK_WORKITEM = REQUIREMENT.C_URI 
where true
 and REQUIREMENT.C_ID = 'DP-317'
 and WORKITEM.C_TYPE = 'systemtestcase'

But this is still hardcoded. And we would have to change the script on the server everytime we change the configuration. That’s why we use parameters that you can pass from the administration in Polarion instead.

You can simply add any parameters into the form configuration. In this case I added the parameter „linkedType“ and set it on „systemtestcase“:

<extension id="velocity_form" label="Latest Test Results" linkedType="systemtestcase" script="testResultFormExtension.vm"/>

I can retrieve this parameter by using the „$attributes“ context variable in the Velocity script:

#set($linkedType = $attributes.linkedType)
$linkedType

By writing $linkedType in the second line, I’m printing this variable and can check if it works after saving the script and reloading the page in Polarion. I don’t have to restart anything:

Now we have to combine this with the sql query.

• Replace the item id with: $object.getId()
• Replace the test case type with: $linkedType ($attributes.linkedType)

The $object variable contains always the old api IWorkItem object of the currently opened item.

But we have to squish it into one line:

#set($linkedTestCaseSQL = "select WORKITEM.C_URI from WORKITEM inner join PROJECT on WORKITEM.FK_URI_PROJECT = PROJECT.C_URI inner join STRUCT_WORKITEM_LINKEDWORKITEMS LINK on WORKITEM.C_PK = LINK.FK_P_WORKITEM inner join WORKITEM REQUIREMENT on LINK.FK_WORKITEM = REQUIREMENT.C_URI where true and REQUIREMENT.C_ID = '$object.getId()' and WORKITEM.C_TYPE = '$linkedType'")

Now we’ll use this sql query to retrieve our linked test cases:

#set($linkedTestCases = $trackerService.queryWorkItems("SQL:($linkedTestCaseSQL)", "id"))

And now we just have to retrieve the test results and render everything:

## Retrieve and render test results of linked test cases
#foreach($linkedTestCase in $linkedTestCases)
	#set($lastTestRecord = $testManagementService.getLastTestRecords($linkedTestCase, 1))
	#if($lastTestRecord.size() > 0)
		$transaction.workItems().getBy().oldApiObject($linkedTestCase).render().withLinks().htmlFor().forFrame() - $lastTestRecord.get(0).getResult().getName()
	#else
		$transaction.workItems().getBy().oldApiObject($linkedTestCase).render().withLinks().htmlFor().forFrame() - No Results
	#end
	<br>
#end

That’s it:

Here the full code example:

## Retrieve parameters
#set($linkedType = $attributes.linkedType)

## Create parametrized SQL query
#set($linkedTestCaseSQL = "select WORKITEM.C_URI from WORKITEM inner join PROJECT on WORKITEM.FK_URI_PROJECT = PROJECT.C_URI inner join STRUCT_WORKITEM_LINKEDWORKITEMS LINK on WORKITEM.C_PK = LINK.FK_P_WORKITEM inner join WORKITEM REQUIREMENT on LINK.FK_WORKITEM = REQUIREMENT.C_URI where true and REQUIREMENT.C_ID = '$object.getId()' and WORKITEM.C_TYPE = '$linkedType'")

## Get all linked test cases
#set($linkedTestCases = $trackerService.queryWorkItems("SQL:($linkedTestCaseSQL)", "id"))

## Retrieve and render test results of linked test cases
#foreach($linkedTestCase in $linkedTestCases)
	#set($lastTestRecord = $testManagementService.getLastTestRecords($linkedTestCase, 1))
	#if($lastTestRecord.size() > 0)
		$transaction.workItems().getBy().oldApiObject($linkedTestCase).render().withLinks().htmlFor().forFrame() - $lastTestRecord.get(0).getResult().getName()
	#else
		$transaction.workItems().getBy().oldApiObject($linkedTestCase).render().withLinks().htmlFor().forFrame() - No Results
	#end
	<br>
#end

I hope this post will help you to create great form extensions 🙂 Let me know what you’ve done with it.