Warning |
---|
Looking for the documentation on the newest versions of Power Actions for Jira 8? Click here and leave these dusty old pages behind! |
On this page:
Table of Content Zone | |
---|---|
|
Basic Usage
The Action script contains instructions that will be executed when calling an action. If you're not yet familiar with SIL, see Simple Issue Language™ usage.
...
In order to help you retrieve the selected value(s) faster, we have created more app-specific SIL routines.
Category | Used with | Routine | Return value |
---|---|---|---|
Single value fields |
| BA_getSingleValue(argv, label) | String representing the value entered or the selected option for the given label. For a checkbox it will return "checked" if the checkbox was selected or an empty string if not. |
Multi value fields |
| BA_getMultiValues(argv, label) | String array representing the selected options. |
| String array containing pairs of original filename and uploaded path. Even indices will contain original filenames, while odd indices will contain an uploaded path. See Examples for usage. | ||
Checkbox |
| BA_isChecked(argv, label) | A method for checking whether a checkbox is selected or not. Returns a boolean: true if the box was checked, false otherwise. |
Date (since v2.0.8 and 2.6.1) |
| BA_getDateValue(argv, label) | This will retrieve a date value from the argv array. Note that for the date time picker, the value in the argv variable uses the user's time zone. BA_getDateValue will convert this value from the user's time zone to the server time zone. |
Note |
---|
These methods are only available in versions 1.0.1 and 2.0.1 and above. |
Let's take the following Screen Script as example.
...
You can also use these in conjunction with array-specific routines like arrayGetElement and arrayElementExists. For a list of available routines that manipulate arrays, see Array routines.
Anchor | ||||
---|---|---|---|---|
|
...
Action Script
Once you have a screen that requires an additional user input, it is necessary to validate that input and let the user know if they did something wrong. This can be done by returning values from the script.
...
Code Block |
---|
string fruit = getElement(argv, 1); if( isNull(fruit) ){ return "What? You don't like fruits?"; } |
Field Validation Errors
If you have multiple input fields on the screen, we recommend to validate them all at once and show errors for each one.
To do this, return an array containing pairs of label and error.
Code Block |
---|
string fruitLabel = getElement(argv, 0); string fruit = getElement(argv, 1); string chocolateLabel = getElement(argv, 2); string chocolate = getElement(argv, 3); string [] errors; if( isNull(fruit) ){ errors = addElement(errors, fruitLabel); errors = addElement(errors, "What? You don't like fruits?"); } if( chocolate != "yes" and chocolate != "of course"){ errors = addElement(errors, chocolateLabel); errors = addElement(errors, "No way!"); } return errors; |
Redirecting and Preventing Refresh
Since version 4.5.5, Power Actions got the ability to redirect to some random page and also to prevent refresh. For this to happen, the return of the action should be of predefined type BActionReturn, which is defined as having the following fields:
- errors, array of BActionError (see below)
- location, string, represents the potential URL to redirect to, leave empty if you want to avoid redirection
- disableRefresh, a boolean, which, if set, will prevent the refresh to be automatically executed at the end of the action
BActionError is a simple structure, containing just two fields:
- field, string, the field is question, leave empty if you want a global error message
- message, string, containing the message, probably you should put something here.
Resolution on the screen is performed in the usual way, if there are errors added in the return, the processing will stop and errors will be shown on the screen. If the location field is filled and there are no errors, a redirect will happen. If the location is empty but the disableRefresh flag is set, the screen will not be refreshed, as usual. This may come in handy when integrating with certain 3rd party addons.
Code Block |
---|
//example excerpt: ................ BActionReturn ret; if(thereAreErrors()) { BActionError e; e.message = "There are errors!"; //global ret.errors += e; } else if(mustRedirect()) { ret.location = "https://google.com?q=SIL"; } else { ret.disableRefresh = true; } return ret; |
We recommend you to use the structure above whenever possible, although the old way is still available (i.e. old scripts do not need to change).
Example
Iterating over uploaded files:
Code Block |
---|
string [] files = BA_getMultiValues(argv, "file"); for(int i = 0; i < size(files); i+=2){ number ORIGINAL_NAME = i; number NEW_PATH = i + 1; desc += "File " + files[ORIGINAL_NAME] + " was uploaded to " + files[NEW_PATH] + "\n"; } |