Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents
maxLevel2

The SIL Listener enables users to execute a script when certain events are triggered.

Managing Listeners

To manage SIL listeners, go to Administration > Listeners.

Image RemovedImage Added

Columns description

ColumnDescription
ListenerFull path to the file and the user to impersonate when running the script. Click to access the file.
EventsEvents for which the listener is configured
ExecutionIndicates whether the execution is synchronous or asynchronous
OperationsPossible operations to do on a listener: edit, delete or enable/disable

Adding a Listener

Each entry for the SIL Listener represents a script that will run for an event. When you add a SIL Listener, you need to define the following properties:

  • Events - event to react to. Required field.
  • SIL Script - the script to run when the event is received. Required field.

    Warning
    titleInfinite Loop

    When you select a script for an event, make sure that the script does not use the raiseEvent routine to raise the same event, as this will cause a loop and crash your Jira instance.

  • Run As - Jira user to impersonate when running the script. If left empty, the script will be run by the currently logged in user. This setting might be necessary if certain scripts require more extensive permissions than those of regular users.
  • Synchronous - If selected, it's a normal listener. If not, it will be scheduled for execution on a separate thread.

Image RemovedImage Added

Tip
titleTips
  • You can add multiple listener entries for the same event.
  • You can map multiple events to the same listener.

Updating a Listener

To update a listener, click the Edit icon in the Operations column on the SIL Listeners page and update the fields in the pop-up window.

Image RemovedImage Added

Deleting a Listener

To remove a SIL Listener, click Delete icon in the Operations column on the SIL Listeners page.

Image RemovedImage Added

Enabling and disabling a Listener

To enable/disable a listener, click the Enable/Disable icon in the Operations column on the SIL Listeners page.
If a listener is disabled, a corresponding label appears next to its path.Image Removed

Image Added

Managing the order of Listeners execution

...

...

This feature is currently available for the Power Scripts™ for Jira server only, we are working on adding it to the cloud version in the near future as well.

If you have more than one listener configured for the same event, you can manage their order of execution by clicking the label on the Events column. A Listener execution order page opens. Use the arrows to define the necessary execution order.Image Removed

Image Added

...

SIL Context

When writing a SIL™ SIL script that will handle an event, the username of the user who triggered the event will be available as the first element in the argv variable and you can use it like this:

...

Also, the issue context (all standard variables and custom field values) will be set to those of the issue where the event was triggered from. For example, if a SIL script is triggered by an event launched from the "TST-123" issue, all standard variables and custom fields used in the SIL™ SIL script will point to the "TST-123" issue, unless specified otherwise using the construction %otherIssueKey% variable.

Info
titleInfo

To edit the actual scripts, use SIL™ Manager.

Aside from the issue events that are configurable from Jira UI, a SIL™ SIL Listener also enables you to react to other events. Note that these events will not run in an issue context since they're not related to an issue, and it doesn't make sense using standard issue variables without qualifying them with the key of the issue. Additionally, each event might add additional information to the argv variable aside from the information that is common for all events.

...

The next elements in the array after these are event-specific and are detailed in the following table.

EventAdditional ParametersNotes

Version Archived

Note

Unavailable on the cloud version


4. version ID

5. string representation of a Version structure. You can retrieve this value and then cast it to a "Version" structure.

Version v = (Version) argv[4];


To get a structure with the changed version, use the getVersionFromEvent routine.

Note

For cloud, please see this page: getVersionFromEvent (the cloud version)

Version Created

Version Moved

Note

Unavailable on the cloud version

Version Released

Version Unarchived

Note

Unavailable on the cloud version

Version Unreleased

Version Merged

Note

Unavailable on the cloud version

4. version ID

5. string representation of a Version structure. You can retrieve this value and then cast it to a "Version" structure.

6. merged version ID

7. string representation of the merged version (cast-able to Version, similar to 5).

Even though you can merge multiple versions into one at once, Jira API only provides reference to a single merged version.

To get a structure with the merged version, you can use the following routines: getMergeToVersionFromEvent, getVersionFromEvent.


Version Updated

To get a structure with the updated version, you can use the getOldVersionFromEvent routine.


Note

For cloud, please see this page: getVersionFromEvent (the cloud version)


Version Deleted

4. version ID

5. empty (the version is already deleted at this point and details are no longer available)

To get a structure with the deleted version, you can use the following routines: getMergeToVersionFromEvent, getFixVersionSwappedToFromEvent, getAffectsVersionSwappedToFromEvent.

Note

For cloud, please see this page: getVersionFromEvent (the cloud version)

Project Created

4. project ID

5. string representation of a Project structure. You can retrieve this value and then cast it to a "Project" structure

To get a structure with the created project, you can use the getProjectFromEvent routine.



Note

For cloud, please see this page: getProjectFromEvent (the cloud version)



Project Deleted

4. project ID

5. project KEY (the project is already deleted at this point and details are no longer available)

To get a strucure with the deleted project, you can use the getProjectFromEvent routine.


Note

For cloud, please see this page: getProjectFromEvent (the cloud version)


Project Updated

To get a structure with the updated project, you can use the getOldProjectFromEventroutine.


Note

For cloud, please see this page: getProjectFromEvent (the cloud version)

Component Created

Note

Unavailable on the cloud version


To get a structure with the created component, you can use the getComponentFromEvent routine.

Component Merged

Note

Unavailable on the cloud version


To get a structure with the merged component, you can use the getComponentFromEvent or getMergeToComponentFromEvent routine.

Component Deleted

Note

Unavailable on the cloud version


To get a strucure with the deleted component, you can use the getComponentFromEvent routine.

Component Updated

Note

Unavailable on the cloud version


To get a strucure with the updated component, you can use the getOldComponentFromEvent routine.
User Created

To get a strucure with the created user, you can use the getNewUserFromEvent routine.


Note

For cloud, please see this page: getUserFromEvent (the cloud version)


User Updated

To get structures with the updated user, you can use the getNewUserFromEvent and getOldUserFromEvent routines.

Note

For cloud, please see this page: getUserFromEvent (the cloud version)


User Deleted

To get a structure with the deleted user, you can use the getDeletedUsernameFromEvent routine.

Info
titleSIL History Routines

To get more information about changes to an issue during an event, see the following out of the box SIL™ routines:

Note

For cloud, please see this page: getUserFromEvent (the cloud version)


Synchronous vs Asynchronous

Most of the listeners you encounter in Jira and see provided by the most of the apps are synchronous. This means that the code runs on the same thread where the event was created. Updating an issue and listening for those changes will trigger the listener(s) which will be executed, and the control is not given back to the user until it is done. This might seem simple, but is not always the best approach.

Suppose you need to keep statistics about users and their engagement with various products. When a user changes an issue on some project, you would like to increment a counter in some external database. Makes no sense to wait for this operation to complete. This is why Power Scripts™ Scripts offers asynchronous listeners, opening the path for better performance and better response time for our users.

...

  1. You do not want to modify the issue(s), and
  2. Performance matters and there is a listener that performs lengthy operations

Mixing asynchronous with synchronous listeners

You can mix asynchronous with synchronous listeners. However, the execution order makes no sense when we talk about asynchronous listeners. The order you establish on the management page is not the order of execution, but the order of launch.