JEditor Automation (beta)

Available in JEditor 3.11.0+
beta since 3.11.0

JEditor Automation is a feature that allows 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's what a sample JEditor automation script looks like:

JEDITOR.automation.create()
.limitTo()
.dialogs('CREATE_ISSUE_DIALOG')
.issueTypes(10000)
.when()
.field('customfield_10600')
.equalsTo('test 2')
.and()
.field('customfield_10600')
.not()
.isDirty()
.then()
.field('customfield_10100')
.setValue('<p>A value that matches test 2</p>')
.compile();

The script consists of the following main parts:

  1. JEDITOR.automation.create()
    This part starts a new script using the Automation API. Automation scripts must always start with JEDITOR.automation.create().
  2. limitTo()
    Use this command to specify the context of the automation rule. The automation rule will be limited by the context provided in this part of the script.
  3. when()
    This is the CONDITIONS part. You can provide as many conditions as you want. Different conditions can be split by and()/or() statement. It is impossible to use both and() and or() in a single script.
  4. then()
    This is the ACTION part. Here, you can provide an id of a JEditor-enabled field and the value/template you want to be populated.
  5. compile()
    This part marks the end of the script. Automation scripts must always end with the compile() keyword.

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

limitTo()

After .limitTo(), you can specify one or more of the following limitations:

  1. dialogs()
    Use this keyword to specify dialogs where the automation rule should work.
    Currently, the following dialog ids are supported:
    • CREATE_ISSUE_DIALOG
    • CREATE_SUBTASK_DIALOG
    • EDIT_ISSUE_DIALOG
    • WORKFLOW_TRANSITION_DIALOG
    You can also provide an arbitrary dialog id (execute JIRA.Dialog.current.options.id in the browser console when the dialog is open to see its id).
    Sample:
    JEDITOR.automation.create()
    .limitTo()
    .dialogs('CREATE_ISSUE_DIALOG', 'CREATE_SUBTASK_DIALOG')
    .when()
    ...
  2. projects()
    Use this keyword to specify the ids of projects. The automation rule scope will be limited to the provided list of projects.
    Sample:
    JEDITOR.automation.create()
    .limitTo()
    .projects(10000, 10100, 10800)
    .when()
    ...
  3. issueTypes()
    Use this keyword to specify the ids of issue types. The automation rule scope will be limited to the provided list of issue types.
    Sample:
    JEDITOR.automation.create()
    .limitTo()
    .issueTypes(10000, 10200)
    .when()
    ...
  4. groups()
    Use this keyword to specify a list of user groups. The automation rule will execute only if the current user is a member of at least one of those groups.
    Sample:
    JEDITOR.automation.create()
    .limitTo()
    .groups('jira-developers', 'jira-testers')
    .when()
    ...
  5. users()
    Use this keyword to specify a list of usernames. The automation rule will execute only if the current user is in the list.
    Sample:
    JEDITOR.automation.create()
    .limitTo()
    .users('johnd', 'admin')
    .when()
    ...

when()

After .when() you can provide a list of conditions. The rule will be executed when the list of conditions is true. Every condition must specify a field id and a requirement. The field with this id will be tested against the requirement.

Sample:

JEDITOR.automation.create()
.when()
.field('customfield_10600')
.equalsTo('my value')
...

In this sample, the field is customfield_10600, and the requirement is field's value must be equal to the string "my value".
Here's the list of requirements that use can use in conditions:

  1. equalsTo()
    This requirement tests a field value against a pre-defined value (provided as an argument).
    Argument:
    • String
    • Array of strings
    Compare to a String when testing the value of a single-value field like radio buttons or a text field.
    Compare to an Array of strings when testing the value of a multi-value field (like a list of checkboxes or a multi-select).
    Sample:
    JEDITOR.automation.create()
    .when()
    .field('customfield_10600')
    .equalsTo('my value')
    .and()
    .field('customfield_10800')
    .equalsTo(['value one', 'value four'])
    ...
  2. contains()
    This requirement tests if a field's value contains a pre-defined sub-value (provided as an argument).
    • String
    • Array of strings
    Compare to a String when testing the value of a single-value field for a substring or when testing the value of a multi-value field for a single checked item.
    Compare to an Array of strings when testing the value of a multi-value field for multiple checked items.
    Sample:
    JEDITOR.automation.create()
    .when()
    .field('customfield_10600')
    .contains('substring')
    .and()
    .field('customfield_10800')
    .equalsTo(['value one', 'value two'])
    ...
  3. isEmpty()
    This requirement tests if the field has no value. Jira's default None value is considered empty.
    Sample:
    JEDITOR.automation.create()
    .when()
    .field('customfield_10600')
    .isEmpty()
  4. isDirty()
    This requirement tests if the user has changed the field.
    Sample:
    JEDITOR.automation.create()
    .when()
    .field('customfield_10600')
    .isDirty()

and(), or()

Use and() or or() keyword to split conditions.

and() requires all conditions to be true simultaneously.

Sample:

JEDITOR.automation.create()
.when()
.field('customfield_10600')
.equalsTo('my value')
.and()
.field('customfield_10800')
.equalsTo('another value')
.and()
...

or() requires at least one condition to be true.

Sample:

JEDITOR.automation.create()
.when()
.field('customfield_10600')
.equalsTo('my value')
.or()
.field('customfield_10800')
.equalsTo('another value')
.or()
...

It is impossible to use both and() and or() in a single script. The rule will use the most recent statement to define the junction of the conditions.

not()

Use not() to negate the test result of any condition.

Sample:

JEDITOR.automation.create()
.when()
.field('customfield_10600')
.not()
.equalsTo('my value')
.or()
.field('customfield_10800')
.not()
.isEmpty()
.or()
...

then()

After then(), you can provide the action of the rule. The action will be executed if the rule context matches the current dialog/issue type/user and if the conditions block returns true.

The action must specify a field id and the value that will be set to the field. You can also use JEditor Templates to populate a field.

Samples:

JEDITOR.automation.create()
.when()
.field('customfield_10000')
.equalsTo('test value')
.then()
.field('customfield_10100')
.setValue('<p>This value will appear in the field 10100</p>')
.compile();
JEDITOR.automation.create()
.when()
.field('customfield_10000')
.equalsTo('test value')
.then()
.field('customfield_10100')
.insertTemplate('JEDITOR_TEMPLATES_TEMPLATE_1g308i1')
.compile();

How to find template ids:

On a regular Jira page, press F12 and switch to the Console tab.

Type the following code and press Enter:

JEDITOR.getTemplates('jeditor_global_templates')

JEditor API will respond with the list of templates, including template names and ids.

To see the list of project-level templates, use the following code:

JEDITOR.getTemplates('jeditor_project_templates')

How to add a rule 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.11.0, you can do the following:

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

mceclip0.png

How do I debug my rule

In the browser console, type the following command:

JEDITOR.log.debug = true

JEditor will log debug-level messages (orange text color) to the browser console. If you reload the page, repeat the command.

Feel free to contact our support team when you need help with automation rules.

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk