JEditor Automation - event listeners (beta) – JEditor Support Central

Available in JEditor 3.18.0+
beta since 3.18.0

JEditor Automation provides API that helps with the conditional population of JEditor-enabled fields. Currently, the feature is in the beta state. We can change the feature's behavior without a prior announcement. It also means that, currently, there's no separate administrative UI for the Automation. Automation scripts can be added in the Custom JavaScript section of the JEditor administrative menu.

Automation script syntax

Here are some samples of JEditor automation listener scripts:

JEDITOR.automation.when()
  .dialog('edit-issue-dialog')
  .created()
  .execute(function (event) {
    // your code goes here
    console.log('EDIT DIALOG CREATED');
  });

JEDITOR.automation.when()
  .dialog()
  .created()
  .promise()
  .then(function () {
    // your code goes here
    console.log('SOME DIALOG CREATED');
  }).catch(function () {
    // your error handling code goes here (optional)
  });

JEDITOR.automation.when()
  .dialog()
  .tabSelected()
  .execute(function (event) {
    // your code goes here
    console.log('TAB SELECTED');
    console.log(event.detail);
  });

JEDITOR.automation.when()
  .jeditor()
  .startedNewComment()
  .execute(function (event) {
    // your code goes here
    console.log('NEW COMMENT STARTED');
    console.log(event);
  });

JEDITOR.automation.when()
  .jeditor()
  .startedInlineEdit()
  .execute(function (event) {
    // your code goes here
    console.log('INLINE EDIT STARTED');
    console.log(event);
  });

JEDITOR.automation.when()
  .jeditor()
  .finishedRenderingField()
  .execute(function (event) {
    // your code goes here
    console.log('FINISHED RENDERING FIELD');
    console.log(event);
  });

Listener scripts consist of the following main parts:

JEDITOR.automation.when()
This part starts a new listener script using the Automation API. The automation listener script must always start with JEDITOR.automation.when().
dialog( [dialog_id1, dialog_id2, ...] )
Use this command to listen to the dialog events. Possible events include dialog created, dialog destroyed, and dialog tab selected. It's possible to limit the listener's scope by providing a list of dialog IDs.
jeditor()
Use this command to listen to JEditor events. Possible events include new comment started, inline editing started, and field rendered.
execute( callback_function )
This command requires an argument - a callback function that executes every time the listener catches the corresponding event.
No other automation commands can be used after execute().
promise()
Use this command to create a promise that resolves when the listener catches the corresponding event.
Promises can only resolve once. Use the promise() command to set a handler that becomes disabled after the first execution.
No other automation commands can be used after promise(), but you can chain then() and catch() to execute code and handle errors.

Please note: spacing (white space before lines in the script) is not mandatory, but we recommend following this style as it makes the script more readable.

dialog()

The dialog() command accepts an optional list of dialog IDs. For example:

JEDITOR.automation.when()
  .dialog('create-issue-dialog', 'create-subtask-dialog')

Execute JIRA.Dialog.current.options.id in the browser console when the dialog is open to see its ID.

Don't put any arguments to catch events of any dialog:

JEDITOR.automation.when()
  .dialog()

After .dialog(), you can specify one of the following commands:

created()
Use this command to listen to the dialog created event. Only works after the dialog() command.
```
JEDITOR.automation.when()
  .dialog()
  .created()
```
destroyed()
Use this command to listen to the dialog destroyed event. Only works after the dialog() command.
```
JEDITOR.automation.when()
.dialog()
.destroyed()
```
tabSelected( [tab_name1, tab_name2, ...] )
Use this command to listen to the dialog tab selected event. Only works after the dialog() command.
It's possible to limit the listener's scope by providing a list of tab names (visible text on the tab).
```
JEDITOR.automation.when()
.dialog()
.tabSelected('Main fields', 'Additional fields')
```

jeditor()

After .jeditor(), you can specify one of the following commands:

startedNewComment()
Use this command to listen to the new comment started event. Only works after the jeditor() command.
```
JEDITOR.automation.when()
.jeditor()
.startedNewComment()
```
startedInlineEdit()
Use this command to listen to the inline editing started event. Only works after the jeditor() command.
```
JEDITOR.automation.when()
.jeditor()
.startedInlineEdit()
```
finishedRenderingField()
Use this command to listen to the field rendered event. Only works after the jeditor() command.
```
JEDITOR.automation.when()
.jeditor()
.finishedRenderingField()
```

execute()

The execute() command accepts a mandatory function argument. It is a callback function that will be executed every time the listener catches a corresponding event that satisfies the listener's scope (e.g. when the listener's scope is limited to a specific dialog ID or a dialog tab name, etc.).

When the callback function is executed, it receives the event as an argument.
event.detail may contain information about the context of the event (see example below).

The execute() command is the terminal command in the chain of a listener script. You cannot chain any other commands after it.

Example:

JEDITOR.automation.when()
  .dialog()
  .created()
  .execute(function (event) {
    if (event.detail?.dialogId === 'create-issue-dialog') {
      console.log('CREATE ISSUE DIALOG');
    }
    else if (event.detail?.dialogId === 'edit-issue-dialog') {
      console.log('EDIT ISSUE DIALOG');
    }
    else {
      console.log('SOME OTHER DIALOG);
    }
  });

promise()

The promise() command returns a Promise object that resolves when the listener catches the corresponding event.

Promises can only be resolved once. Use the promise() command to set a handler that becomes disabled after the first execution.

No other automation commands can be used after promise(), but you can chain then(), catch(), and finally() to execute code and handle errors.

Example:

JEDITOR.automation.when()
  .dialog()
  .created()
  .promise()
  .then(function (event) {
    if (!event.detail?.dialog?.querySelector('#customfield_10200')) {
      throw new Error('Field customfield_10200 is missing!');
    }
    console.log(event.detail?.dialog?.querySelector('#customfield_10200').value);
  }).catch(function (error) {
    console.error(error);
  });

How to add a listener to my JEditor Configuration

Currently, there's no separate UI for JEditor Automation. We will add it in one of the future releases.

After upgrading to JEditor 3.18.0, you can do the following:

Go to Jira administration > Manage apps > JEditor > Custom JavaScript.
Add the automation script to the JavaScript field
Save

How do I debug my rule

Call debugger in the callback or chained function:

JEDITOR.automation.when()
  .dialog()
  .created()
  .execute(function (event) {
    if (AJS.Meta.get('remote-user') === 'myusername') {
      debugger;
    }
  });

JEDITOR.automation.when()
  .jeditor()
  .startedNewComment()
  .promise()
  .then(function () {
    if (AJS.Meta.get('remote-user') === 'myusername') {
      debugger;
    }
  });

Please note: replace myusername with your Jira user's username. The condition is added to prevent other Jira admins from going into the debug mode.
The debug mode will start only if the browser developer tools window is open. Press F12 to start the browser developer tools.

Feel free to contact our support team when you need help with listeners or have a request for more commands/arguments.

JEditor Automation - event listeners (beta)