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

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.

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.

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.

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.