Often, during the development of an integration or a special customization, people get stuck because of the lack of context. Questions appear: which user pressed on the next status button ? did the manager approved this item? What was the result of the calculation in the previous step? The traditional way of dealing with such questions was to create additional custom fields to keep that data, usually hidden from users (so excluded from the screens schemes), effectively adding bloat to Jira and ultimately worsening indexing - and general - performance. To help you answer these kind of questions, SIL acquired, starting with version 4.1.7 of katl-commons, a new feature, called persistent variables.
So, what's a persistent variable? In short, in an issue context, a persistent variable is a value inherently linked to the issue. Think of it like an extension of the issue fields, or - making a rather bad analogy - an additional custom field, but internal to SIL. Outside the issue context, the persistent variable becomes a global variable, accessible from all scripts.
It is better to see some usage, so you will figure out what it means and how it can simplify your SIL throughout your Jira integration.
Usage in an Issue Context
Persistent variables are introduced via the persistent keyword. In order to save space, we do not allow persistent and constant modifiers to be used on the same variable, so you can't have both. A persistent variable is always modifiable.
Let's install the following postfunction on an easy executable action (like "Start Progress" on the default simplified workflow of Jira), and execute the transition a number of times (a normal Start-Stop progress cycle, in this example, on the same issue)
persistent number counter = 1;
persistent boolean flag = false;
description += "\n" + counter + "(" + flag + ")";
flag = !flag;
counter ++;
The above example adds some text to the description of an issue, but unlike the version without the persistent keyword, the appended text will be something like:
1(false) 2(true) 3(false) 4(true)
So what's happening here? The truth is that the initialization of the variable happens only once. Subsequent executions will find the persistent variable initialized, and will load that particular value, and start from there. The flag will therefore flip and the counter will be incremented with each executed transition on that issue.
What's more is that if you move to another issue and execute the same postfunction multiple time, you will get a similar output. The first line of the output will still be 1(false) followed by 2(true) and so on ... which means that the persistent variable is linked to that issue.
Let's suppose now that we have a SIL listener and we'll like to use that counter variable. You can simply access it in your listener like this:
persistent number counter; persistent boolean flag = true; //initialization is ignored if the previous script was already executed! //............. /// use it in the listener like a normal variable: counter--;
You should note that we didn't put any initializer; if the variable is already initialized the initializer is simply not executed at all, no matter the construct. While such behavior belongs to the logic of the persistent variable, you may find this rather strange and sometimes prone to errors. We recommend you to use the same initializer everytime (maybe a constant?) so you won't start with different values
In conclusion, the persistent variable:
- linked to the current issue from the context,
- its initializer is just executed first time (no matter the right expression, the right expression is totally ignored)
- a variable whose value survives the script, making it available in some other scripts under the same name
Usage Outside the Issue Context
The usage outside the issue context is the same. However, due to the nature of the persistent keyword, the variable becomes a global variable. Take for instance the following script, run from the SIL Runner gadget:
persistent number counter = 1;
persistent boolean flag = false;
TEST-1.description += "\n" + counter + "(" + flag + ")";
flag = !flag;
counter ++;
Counter will be incremented as before (starting from 1) and the text above will be re-appended to the issue 'TEST-1'
However, if we change just the issue, say to 'TEST-2', the counter will maintain it's previous value, incrementing from the value it stopped when you run the above for the TEST-1 issue. Just try it !
Persistent variables are effectively global if used outside of the issue context.
Helper Routines
Two helper routines are available to deal with persistent vars:
getPersistentVar([issue_key,] varName); setPersistentVar([issue_key,] varName, value);
Values are treated like strings. For the above example:
string globalCounterVar = getPersistentVar("counter");
number test_one_counter = getPersistentVar("TEST-1", "counter"); //notice the implicit cast! values are treated like strings, though!
Some Notes
Although useful, persistent variables come with a small performance penalty. Don't overuse them!
There's no way to delete a persistent var (other than direct SQL) at the moment. Think hard if you really need them.