Availability
This routine is available starting with
- Power Scripts™ 2.5 (server)
- SIL Engine™ (former katl-commons) 2.5
Syntax
lfWatch(field, relatedFields, scriptPath[,javaScriptEvents]);
Description
Attaches listeners for the events that you give as parameters in the function. If you don’t specify any events, this routine attaches listeners to the “change” event which is triggered when the issue is updated. Every time when the event is triggered, the SIL™ script from scriptPath parameter runs. This SIL™ script receives the values for the relatedFields parameter and you can use them as: argv[field].
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
field | String | Yes | Field to listen to |
relatedFields | Array String | Yes | Dependent fields required for the given field |
scriptPath | String | Yes | Script source to run when the event is triggered |
javaScriptEvents | Array | No | Events to listen to. It's any JavaScript event (check this list for example). Starting with SIL Engine™ v 4.1.1, you can also listen to the following Jira events: inlineEditSaveComplete, newContentAdded, issueRefreshed which refer to the inline editing on the view issue screen Jira UI events. |
"change" event
When using the "change" event on a "labels type" field (fixVersions, Affected Versions, Labels, Components, etc.), the event will never trigger when a label is deleted, but only when labels are added. We have noticed that for these fields the "focusing" event closely matches the behavior expected for the "change" event.
Example
lfWatch("summary", {"summary", "customfield_13706","components"}, " hook.sil", {"keyup"}); //where field = "summary";relatedFields = {"summary", "customfield_13706","components"};scriptPath = " hook.sil";javaScriptEvents = {"keyup"}
For the scriptPath parameter you can either give the relative path (as in the example above), or the absolute path:
C:/Program Files/Atlassian/Application Data/JIRA/silprograms/hook.sil.
// hook.sil : if (contains(argv["summary"], "important")) { lfSet("priority", "Highest"); lfShowFieldMessage("priority", "Priority changed", "INFO"); }
Every time when the keyup event is triggered, the hook.sil is executed. When the Summary field contains the word “important”, the Priority field is set to "Highest" and a message is displayed for the priority field.
The first image shows the initial value of the priority for the current issue, the next one shows the value it is changed to, after executing the code from hook.sil.
The values from the relatedFields parameter are accessed as argv[field]. For fields that can take multiple values (like components or affectedVersions), the value returned is in the following format: val1|val2|val3.
Info
For more information, see How Live Fields work.
See also