Skip to end of metadata
Go to start of metadata

Contents

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

Managing Listeners

To manage SIL listeners, go to Administration > Listeners.

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.

    Infinite 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.

Tips

  • 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.

Deleting a Listener

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

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.

Managing the order of Listeners execution

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.

SIL Context

When writing a 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:

string callingUser = getElement(argv, 0);

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 script will point to the "TST-123" issue, unless specified otherwise using the construction %otherIssueKey% variable.

Info

To edit the actual scripts, use SIL™ Manager.

Aside from the issue events that are configurable from Jira UI, a 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 first three elements in the argv string array are (note that indexing in the array starts with 0):

  1. The user that triggered the event
  2. An internal id for the event that was triggered. Normally you wouldn't need this.
  3. The name of the event as specified in the dropdown list that configures the listener.

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

EventAdditional ParametersNotes

Version Archived

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.

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

Version Created

Version Moved

Unavailable on the cloud version

Version Released

Version Unarchived

Unavailable on the cloud version

Version Unreleased

Version Merged

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.


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.

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.



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.


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


Project Updated

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


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

Component Created

Unavailable on the cloud version


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

Component Merged

Unavailable on the cloud version


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

Component Deleted

Unavailable on the cloud version


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

Component Updated

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.


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.

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.

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 offers asynchronous listeners, opening the path for better performance and better response time for our users.

However, keep in mind that with asynchronous operations, you are not allowed to modify the issue because modifications will be discarded upon exit. With synchronous operations, you are allowed to modify that issue.

So, we recommend that you use synchronous listeners for the following cases:

  1. You want to modify the issue(s), or
  2. There's a sequence of operations that need to be respected and those cannot be packed in a single script, or
  3. Listener execution is short

Use asynchronous listeners when:

  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.