Advanced: The Work Item Pre-Save Hook – checking Work Items before saving

Checking, if the entered data is correct, before saving a Work Item in Polarion – this is made possible by a small extension on the extension portal.

I want to show it with a small example: If I set a date in a custom field, I should have to explain, why I chose this date. So it should be enforced, that I fill in the explanation field, before being able to save.

To enable you using pre-save hooks, download the following extension: https://extensions.polarion.com/extensions/134-fmc-work-item-save

Deploy the extension in your Polarion System. Basically putting it in „Polarion\polarion\extensions\ANYNAME\eclipse\plugins“.
It’s more detailed described in the readme of the extension:

Now lets get back to what we wanted to do: Enforcing a description for a given date in a Work Item.

To achive this, I can use a simple pre-save hook. A script that is executed before a Work Item (or Document etc.) is saved. Therefore I create a script in the folder „Polarion/scripts/workitemsave“ (Create one, if it doesn’t exist). If I name the script „systemrequirement-pre-save.js“ it will be executed for all System Requirements on the whole Server, every time somebody saves a System Requirement. Name it „pre-save.js“ and it will be executed for every Work Item.

As the ending shows, this is a javascript. You get the Work Item that’s saved as object of IWorkItem as variable „workItem“. In the end the script wants a returnvalue. If the returnvalue is an empty string, it will let the user save the Work Item. If there is text stored in the value, it will show an error message.

To do what I did, the following code is enough:

// Note: Unfortunately we cannot use throw() or return()
// to exit this script.
var returnvalue = "";

// First of all we check, if the field "value1" has a value 
// then we check, if the "whyDate" has a value.
// If the user entered a value in the value1 field, but not in the WhyDate field,
// it won't save and throw returnvalue as error message
if (workItem.getCustomField("value1")) {
	// Check if a reason is set for this date
	if (workItem.getCustomField("whyDate")){
		var returnvalue = "";
	} else {
		var returnvalue = "Please give a reason for the date in the field 'Why Date'";
	}
}

// The statement at the end of the script defines the return
// value- if 'returnvalue' is empty, workitem will be saved,
// otherwise the value of returnvalue is returned to the user
// as error message
returnvalue;

Another interesting use case is to check the description of requirements for weak words and give users the hint to change them.

But pay attention: this will create server-load for every save. So be careful and don’t use save-hooks when not needed. Even if one check just needs 0.1 seconds. It can accumulate quickly to a noticable performance reduction.

To use the scripts for just one project, you can add the project id to the file name. For example „elibary-requirement-pre-save.js“.