Documentation for JIRA 6.3 EAP developer (EAP) releases only. Not using this? See below:
(JIRA 6.2.x documentation | JIRA OnDemand documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

Jelly is a scripting and templating language from Apache's Jakarta project. It is similar to Ant, in that scripts are XML, and each tag maps to a Java class, but has a more sophisticated internal pipeline model for tag interaction, much like JSP taglibs. See the Jelly website for more details.

JIRA comes with a number of Jelly tags implementing core operations in JIRA. This provides a scriptable interface to JIRA. There are many possible uses for JIRA Jelly tags, the most common being importing data into JIRA from other systems, and automating common administrative tasks (see the examples below).

Enabling Jelly

JIRA's Jelly support is disabled by default, as Jelly, in principle, allows running arbitrary Java code on the server under the Tomcat account. In some environments this may be considered a security risk, depending on who is allowed to configure and run Jelly scripts (a 'JIRA System Administrators' permission is required). We recommend to use Jelly only when you absolutely cannot do without it and disable Jelly support when you do not need it any more.

To enable Jelly, set the jira.jelly.on system property when starting your application server. System properties are set with parameters to the java command, e.g. java -Djira.jelly.on=true ... (You can set this parameter in the setenv.sh file in your /bin folder)

How to set this property depends on your application server. For example, set the environment variable JAVA_OPTS=-Djira.jelly.on=true, or when running JIRA as a service, set the service JVM parameter.

Running a Jelly script

To run a Jelly script once:

  1. Log in as a user with the 'JIRA System Administrators' global permission.
  2. Choose > System. Select Advanced > Jelly Runner to open the Jelly Runner page.
    (tick) Keyboard shortcut: 'g' + 'g' + type 'jel'
  3. Paste your Jelly script into the text area.

To run a Jelly script periodically:

  • Configure a service with the following class: com.atlassian.jira.jelly.service.JellyService
 

Restricting Jelly

To remove the interface for pasting scripts in:

  1. Edit atlassian-jira/secure/admin/views/jelly_runner.jsp
  2. Add the disabled attribute to the textarea, e.g.
    <ui:textarea label="text('admin.jellyrunner.jelly.script.xml')" name="'script'" rows="'40'" cols="'80'" disabled="true" /> 

This prevents text being pasted into the Jelly Runner page. Note that this is only an interface change and it will be still possible to run Jelly scripts by submitting an HTTP request with the right content.

On this page:

Writing a Jelly script

 

Scripts are generally of the form:

There are also a few extra tags that can be accessed by using the following outer tag, instead of the one above (these are tags that were formerly restricted to the now-defunct JIRA Enterprise edition):

In addition to the JIRA tags, you can use tags from the email, http, soap, sql and core Jelly taglibs. More can be added by the user if necessary.

Many of JIRA's Jelly tags set context variables, so subsequent tags can refer to their output by dereferencing the context variable (e.g. ${jira.new.username}). Other tags let you explicitly specify the name of a variable to store some output in, e.g., <jira:CreateUser> has issueKeyVar and issueIdVar parameters:

Note that the variable is only set after the tag is closed, not inside the tag.

(minus) Please Note: Due to this variable interpolation, if your text contains anything of the form ${something} , you need to escape this as $${something} to prevent the 'variable' being expanded to a blank string.

When specifying the value of an attribute, note the following special characters must be escaped.

Special Character

Escaped equivalent

ampersand (&)

&amp;

apostrophe or single quote (')

&apos;

double quote (")

&quot;

less than (<)

&lt;

greater than (>)

&gt;

The list of currently available tags:

jira:AddActorsToDefaultProjectRole

This tag will add 'actors' to the default membership for a given project role. Actors can be defined as groups or users, i.e. you can add both users and groups to a project role.

Attributes

Attribute Name

Type

Default Value

Description

projectroleid

int

 

This is the id of the project role.

actors

string

 

A comma delimited list of either users or groups

actortype

string

 

This defines the type 'actor' you are sending to the tag. Currently this field can contain either 'atlassian-user-role-actor' for users, or 'atlassian-group-role-actor' for groups.

Examples

Adding a list of default users or groups to a project role

jira:AddActorsToProjectRole

This tag will add 'actors' to a given project role for a particular project. Actors can be defined as groups or users, ie you can add both users and groups to a project role.

Attributes

Attribute Name

Type

Default Value

Description

projectroleid

int

 

This is the id of the project role.

actors

string

 

This a comma delimited list of either user names or group names

actortype

string

 

This defines the 'actor' type. Currently this field can contain either 'atlassian-user-role-actor' for users, or 'atlassian-group-role-actor' for groups.

projectkey

string

 

This is the key of the project you wish to add users or groups to for the specified role.

Examples

Adding a list of users or groups to a project role

jira:AddComment

This function adds a comment to an Issue.

Attributes

Attribute Name

Type

Default Value

Description

issue-key

string

 

The issue to add the comment to (required).

commenter

string

Currently logged in user

Username of the user to make the comment (Must have browse and comment permissions).

comment

string

 

Comment to be added to the issue (required).

groupLevel

string

none

Name of group that can see this comment. NOTE: If this is specified you can not specify the roleLevel parameter.

roleLevel

string

none

Name or Id of Project Role that can see this comment. NOTE: If this is specified you can not specify the groupLevel parameter.

created

string

Current Date/Time

Date/Time the Comment was created in format yyyy-MM-dd hh:mm:ss.0

updated

string

Current Date/Time

Date/Time the Comment was last updated in format yyyy-MM-dd hh:mm:ss.0. This can be used if you are trying to import a comment with specific pre-existing values.

editedBy

string

Currently logged in user

Username of the user who last updated the comment. This can be used if you are trying to import a comment with specific pre-existing values.

tweakIssueUpdateDate

boolean

true

If an updated date is provided, the issue's updated date will be updated with that value. If the tweakIssueUpdateDate parameter is set to false, the issue's updated timestamp will be left untouched.

Examples

Create comment

Create Issue and Comment

jira:AddComponent

Adds a component to a project.

Attributes

Attribute Name

Type

Default Value

Description

project-key

string

 

The key of the project you want to add the component to (not required if nested inside atag).

name

string

 

Name of the component (required).

description

string

 

Description of the component.

componentLead

string

 

The username of the Component's lead. Leave blank for no lead.

Examples

Create Component

Create Component in a Project

Create Component with a Component Lead

jira:AddFieldToScreen

Adds a field to a specific tab on a screen. Can also specify in which position to insert the field.

Attributes

Attribute Name

Type

Default Value

Description

ffldId

string

 

Field ID of the field to add (required). e.g. "description", "duedate", etc.

screen

string

 

Screen ID or Name (required). e.g. "1" or "Default Screen".

tab

string

0

Tab ID or Name. e.g. "0" or "Field Tab".

fieldPosition

int

last position

Position to insert the field into. Range of values is from 1 to the number of fields on the screen.

Examples

Add Fields to a Screen

Create a new Customfield and Add it to a Screen

jira:AddPermission

Grants permissions within a permission scheme. Often nested within a JIRADOC:CreatePermissionScheme tag.

Attributes

Attribute Name

Type

Default Value

Description

schemeId

string

 

If not nested in a CreatePermissionScheme tag, specifies the scheme Id to add the permission to (0 is the default permission scheme).

permissions

required string

 

A comma-separated list of permissions to grant:
StringPermission

  • Project — Administer projects
  • Browse — Browse projects
  • Create — Create issues
  • Edit — Edit issues
  • ScheduleIssue — Schedule issues
  • Move — Move issues
  • Assign — Assign issues
  • Assignable — Assignable user
  • Resolve — Resolve issues
  • Close — Close issues
  • ModifyReporter — Modify reporter
  • Comment — Add comments
  • CommentEditAll — Edit all comments
  • CommentEditOwn — Edit own comments
  • CommentDeleteAll — Delete all comments
  • CommentDeleteOwn — Delete own comments
  • Delete — Delete issues
  • Work — Work on issues
  • WorklogEditAll — Edit all worklogs
  • WorklogEditOwn — Edit own worklogs
  • WorklogDeleteOwn — Delete own worklogs
  • WorklogDeleteAll — Delete all worklogs
  • Link — Link issues
  • Attach — Create attachments
  • AttachDeleteAll — Delete all attachments
  • AttachDeleteOwn — Delete own attachments
  • ViewVersionControl — View version control
  • ViewVotersAndWatchers — View voters and watchers
  • ManageWatcherList — Manage watcher list
  • SetSecurity — Set issue security level

type

string

 

Type of recipient for the permission:

  • group
  • projectrole
  • user
  • lead
  • assignee
  • reporter
  • userCF
  • groupCF

group

string

 

If type is 'group' (or type is unspecified), specifies the group name to grant permissions to.

projectroleid

int

 

If type is 'projectrole', specifies the id of the projectrole to grant permissions to.

user

string

 

If type is 'user', specifies the user name to grant permissions to.

userCF

string

 

If type is 'userCF', specifies the id of a User custom field, e.g. 'customfield_10000', identifying the user to be granted the permission.

groupCF

string

 

If type is 'groupCF', specifies the id of a group-selecting custom field (e.g. a select-list with group names as values) whose members should be granted this permission. E.g. 'customfield_10000'.

Examples

Grant permissions to jira-users and jira-developers in a new permission scheme
(See also the JIRADOC:example scripts)

Grant issue reporters the ability to edit/delete their own issues, in a new permission scheme

Make projects using default permission scheme visible to certain users

Granting a group selector custom field's members the ability to assign/be assigned the issue.

jira:AddUserToGroup

Makes a user a member of a Group. Adds the username and/or group name into the context if specified.

Attributes

Attribute Name

Type

Default Value

Description

username

string

 

Username to add to Group (required if not in atag).

group-name

string

 

Group to add User to (required if not in atag). Note: if the group has the 'JIRA System Administrators' global permission, and the logged-in user does not, an error message will be displayed and the operation will not succeed.

Username is set in the context if specified in the tag.Group name is set in the context if specified in the tag.h4. Examples

Add User to Group

Add New User to Group

Add User to New Group

Add New User to New Group

jira:AddVersion

Adds a version to a project.
Attributes

Attribute Name

Type

Default Value

Description

project-key

string

 

The key of the project you want to add the component too (not required if nested inside atag).

name

string

 

Name of the version (required).

description

string

 

The description of the version.

releaseDate

string

 

The release date of the version.

schedule

string

 

Schedule of the version.

Examples

Create a Version

Create a Version in a Project

jira:AssignIssue

Assigns an issue to a user.

Attributes

Attribute Name

Type

Default Value

Description

key

string

 

Key of the issue to assign.

assignee

string

 

User to assign issue to.

Examples

Create and assign issue

jira:AttachFile

Attaches a file to an issue.

Attributes

Attribute Name

Type

Default Value

Description

key

string

 

Key of the issue to attach the file to. (Required)

filepath

string

 

Path (on the server) of the file to attach. (Required)

option

string

add

Behavior when a file with same name is already attached. (Optional). The options are:

  • skip — do not attach file if a file with this name is already attached.
  • override — overwrite existing attached file
  • add — add the file as another attachment

created

string

Current Date/Time

Date/Time the attachment was created, in format yyyy-MM-dd hh:mm:ss.0 (Optional)

Examples

Adding an attachment

jira:CreateCustomField

The tag creates a new Custom Field. Only System custom fields can be added with Jelly tags.

Attributes

Attribute Name

Type

Default Value

Description

fieldType

string

 

Field type as appears as the key in the plugin descriptor

fieldScope

string

 

One of global, project or issuetype

fieldName

string

 

Name of custom field

projectKey

string

 

Key of the related project. Only valid for scope "project"

issueType

string

 

Issue type. Only valid for scope "issuetype"

description

string

 

Description of the field to be displayed when adding a value

searcher

string

 

A valid related custom field searcher

 List of valid system searchers...
  • textsearcher
  • exacttextsearcher
  • daterange
  • datetimerange
  • exactnumber
  • numberrange
  • versionsearcher
  • projectsearcher
  • userpickersearcher
  • userpickergroupsearcher
  • grouppickersearcher
  • selectsearcher
  • radiosearcher
  • cascadingselectsearcher
  • multiselectsearcher
  • checkboxsearcher
  • labels

customFieldIdVar

string

 

The name of the variable to place the new custom field.

Examples

Create Cascading Custom Field
jira:AddCustomFieldSelectValue subtag can be used to add values for select lists. They can also be nested for Cascading Select Lists.

jira:CreateGroup

Creates a Group in JIRA.

Attributes

Attribute Name

Type

Default Value

Description

group-name

string

 

Name of group to create (required).

Context Variables

Context Variable

Type

Description

jelly.group.name

string

Name of group being created.

Examples

Create Group

jira:CreateIssue

This tag creates a new issue in JIRA and places the issue id in the context.

Attributes

Attribute Name

Type

Default Value

Description

project-key

string

 

Key of the project to add the issue to (required if not nested in atag).

issueType

string

First issue type

The string name of the Issue Type this issue should be created for (e.g. Bug).

summary

string

 

Summary of the issue being created (required).

priority

string

First priority

The string name of the Priority (e.g. Major).

components

string

 

The string name of the Component.

versions

string

 

The string name of the Affected Version.

fixVersions

string

 

The string name of the Fix For Version.

assignee

string

 

The username of the user to assign this issue to (logged in user requires the assign issue permission and user specified requires the assignable permission). Set to "-1" for Automatic assignment.

reporter

string

(see description)

The username of the user who is reporting this issue. The user is logged in and then the issue is created. The user is logged out again when the Create Issue tag closes.
If the logged in user does not have Modify Reporter privilege, then the default value of this attribute is the username of the logged in user. If, however, the logged in user does have Modify Reporter privilege, there is not a default value, and this attribute is mandatory. See JRA-12984 for further explanation.
(Broken? See JRA-5620.)

environment

string

 

Description of the environment.

description

string

 

Detailed description of the issue.

duedate

string

 

Due date of the issue. The format required is the current JIRA date format.
Note: As the default JIRA date format is locale-specific (e.g. 12/Jan/05), you may wish to use the yyyy-mm-dd ISO format instead. To do this, set the following properties on JIRA's 'Advanced Settings' page:

  • jira.date.picker.java.format to value yyyy-MM-dd
  • jira.date.picker.javascript.format to value %Y-%m-%e

    (info) See Changing the Due Date Input Format for more information about changing these values.

created

string

Current Date/Time

Date/Time the Issue was created in format yyyy-MM-dd hh:mm:ss.0

updated

string

Current Date/Time

Date/Time the Issue was updated in format yyyy-MM-dd hh:mm:ss.0

issueIdVar

string

 

The name of the variable to place the ID of the new Issue.

issueKeyVar

string

 

The name of the variable to place the Key of the new Issue.

duplicateSummary

string

 

Setting this attribute to 'ignore' will allow Issue with the same summary to be created.

security-level

string

 

Sets the security level of an issue. Value is the name of a level, e.g. 'Secret'.

Examples

Create Issue

Create Issue from Project
This example is more complicated as a permission scheme is required for the project before an issue can be created.

Create Issue with Custom Field values
Use the subtag jira:AddCustomFieldValue

Attribute Name

Type

Description

id

long

ID of the custom field with the customfield_ prefix

value

string

string representation of the custom field value. Note that this may be different to the displayed value (e.g. The project picker uses the project id as the String value but displays the project name)

key

string

Key is used for multi-dimensional data. Currently, only Cascading selects supports its use. Omit to specify the value of parent, use "1" as the value for child

name

String

deprecated Name of the custom field.

(info) Using the name attribute has been deprecated. While it will work in 3.0 its use is discouraged.

Note:

  • To view the <customFieldId>,
    1. Navigate to Administration -> Issue Fields -> Custom Fields
    2. Hover your cursor over the "Configure" link of the custom field
    3. You can view the <customFieldId> in the status bar of your browser
  • To view the "Parent Option Id" and "Child Option Id" for Cascading Select fields,
    1. Navigate to Administration -> Issue Fields -> Custom Fields -> Configure -> Edit Options -> Edit
    2. You can view the <selectedParentOptionId> ("Parent Option Id") and <selectedValue> ("Child Option Id") in the status bar of your browser

jira:CreatePermissionScheme

Creates a Permission Scheme

Attributes

Attribute Name

Type

Default Value

Description

name

required string

 

Name of the permission scheme.

description

string

 

Permission scheme description.

Context Variables

Context Variable

Type

Description

jelly.permission.scheme.id

string

Id of the created permission scheme

jira:CreateProject

This tag creates a new project in JIRA and places the project id in the context.

Attributes

Attribute Name

Type

Default Value

Description

key

string

 

The project key used to create Issue Keys (required).

name

string

 

The name of the project (required).

lead

string

 

The username of the user that is the project lead (required).

url

string

 

The URL of the site for this project.

description

string

 

The description of this project.

Context Variables

Context Variable

Type

Description

jelly.project.id

string

Id of the Project that was created.

jelly.project.key

string

Key of the Project that was created.

Examples

Create Project

jira:CreateProjectRole

This tag will create a project role with the given name and description.

Attributes

Attribute Name

Type

Default Value

Description

name

string

 

The name for the project role you will be creating

description

string

 

The description for the project role you will be creating

Context Variables

Context Variable

Type

Description

jelly.role.id

Long

The id of the project role

jelly.role.name

string

The name of the project role

jelly.role.description

string

The description of the project role

Examples

Creating a new project role

jira:CreateUser

Creates a user in JIRA and places their username in the context.

Attributes

Attribute Name

Type

Default Value

Description

username

string

 

Username of the user being created (required).

password

string

 

User's password. If the password field is left blank, a random password will be auto-generated.

confirm

string

 

Confirmation of users password (required).

fullname

string

 

Descriptive name of the user (required).

email

string

 

Email address of the user (required).

sendEmail

boolean

false

If provided, specifies whether to send a confirmation email.

Context Variables

Context Variable

Type

Description

jelly.new.username

string

Username of the user being created.

Examples

Create User

jira:DeleteProjectRole

This tag will delete the project role with the given id.

Attributes

Attribute Name

Type

Default Value

Description

projectroleid

int

 

The id of the project role you want to delete.

confirm

string

 

To delete the project role this value must be set to 'true'.

Examples

Deleting a project role from JIRA

jira:GetDefaultRoleActors

This tag will return a ProjectRoleActors object for a given project role for a particular project. This object carries the members of a project role, i.e. users and/or groups. To get the collection of users in this object, use the expression ${roleactors.users} where roleactors is the variable name of the object. For more information on the RoleActors object, consult the JIRA API.

Attributes

Attribute Name

Type

Default Value

Description

projectroleid

int

 

The id of the project role you want to query

var

string

 

The name of the variable you wish to have the returned role actors placed into

Examples

Returning a List of role actors and iterating over the users in each of these actors.

jira:GetProjectRole

This tag will return the project role with the given id.

Attributes

Attribute Name

Type

Default Value

Description

projectroleid

int

 

The id of the project role you want

var

string

 

The name of the variable you wish to have the project role assigned to

Examples

Returning a project role

jira:GetProjectRoleActors

This tag will return a ProjectRoleActors object for the given project role and project. This object is a placeholder for the internal members of a project role, i.e. users and/or groups. To get the collection of users in this object, use the expression ${roleactors.users} where roleactors is the variable name of the object. For more information on the RoleActors object, consult the JIRA API.

Attributes

Attribute Name

Type

Default Value

Description

projectkey

string

 

The key of the project you want to query

projectroleid

int

 

The id of the project role you want to query

var

string

 

The name of the variable you want the returned 'role actors' object assigned to

Examples

Return a list of users for a given 'Role Actors' object

jira:IsProjectRoleNameUnique

This tag will return 'true' or 'false' to let you know if there is already a project role with the given name.

Attributes

Attribute Name

Type

Default Value

Description

name

string

 

The name of the project role

var

string

 

The name of the variable you want the returned result assigned to.

Examples

Determining if a project role is unique.

jira:LinkIssue

This tag creates a link from one issue to another issue.

Attributes

Attribute Name

Type

Default Value

Description

key

string

 

The key of the issue to link from (origin of link - required)

linkKey

string

 

The key of the issue to link to (destination of link - required)

linkDesc

string

 

linkDesc is taken from the 'Inward Description' or the 'Outward Description' of the link. (required)

Examples

Create a Link between two existing issues

Create two issues and link them

jira:Login

This tag logs a user into JIRA using the username and password provided. Use this tag when you are running the Jelly script in a manner in which you are not logged in (for example, if you are running a JellyService instead of using the Jelly Runner), or if you want to run the Jelly script as a different user to the one you are logged in as.

Attributes

Attribute Name

Type

Default Value

Description

username

string

 

Username of the user to log in.

password

string

 

Password of the user to log in.

Context Variables

Context Variable

Type

Description

jelly.user

User

User logged in.

jelly.username

string

Username of the User logged in.

Examples

Login a user in with username and password and set in context

jira:RemoveActorsFromDefaultProjectRole

This tag will remove a list of role actors (i.e. users and/or groups) from the default membership of a given project role.

Attributes

Attribute Name

Type

Default Value

Description

projectroleid

int

 

The id of the project role you wish to remove default actors from

actors

string

 

A comma delimited list of users or groups you wish to remove from the default project role

actortype

string

 

The type of 'actor' you are removing. Currently the available options are 'atlassian-group-role-actor' or 'atlassian-user-role-actor'

Examples

Removing a list of groups from a default project role

jira:RemoveActorsFromProjectRole

This tag will remove a list of role actors from a given project role for a given project.

Attributes

Attribute Name

Type

Default Value

Description

projectroleid

int

 

The id of the project role you wish to remove members from

actors

string

 

A comma delimited list of users or groups you wish to remove from the project role

projectkey

string

 

The key of the project the project role is associated with

actortype

string

 

The type of 'actor' you are working with. Currently the available options are 'atlassian-group-role-actor' or 'atlassian-user-role-actor'

Examples

Removing a list of groups from a project role

jira:RemoveUser

Removes an existing JIRA user by their username

Attributes

Attribute Name

Type

Default Value

Description

name

string

 

Username of the user to remove (required).

Examples

Remove User

jira:RunSearchRequest

This tag runs a search request against JIRA using a predefined filter.
Note: This tag will return a GenericValue for each issue which matches the search request.
A GenericValue consists of key-value pairs, e.g.

To retrieve a value, e.g. key, you can call gv.getString("key"). For full details, see the OFBiz GenericValue API.

Attributes

Attribute Name

Type

Default Value

Description

filterid

int

 

The id of the filter which will be used to run the search request.

size-var

string

 

The variable that will hold the number of issues returned from the search request.

var

string

 

The variable that will hold the issues returned from the search request.

Examples

Running a search request and iterating through the keys of the returned issues

jira:SelectComponentAssignees

Selects the default assignees for newly created issues of the component.

Attributes

Attribute Name

Type

Default Value

Description

project-key

string

 

The key of the project you want to add the component to (required).

componentName

string

 

Name of the component (required).

assigneeType

string

 

Default assignee type (required).
Assignee Types:

  • projectDefault
  • componentLead
  • projectLead
  • unassigned

Examples

Select a Component Assignee

jira:TransitionWorkflow

(minus) Please Note: This tag is not available in 3.3 and 3.3.1 — see JRA-7690 for details.

This tag executes a workflow transition on an issue.

Please keep in mind that if you are specifying field attribute/value pairs in your Jelly tag then these fields MUST be on the associted workflow transition screen. If the field is not on the screen then the value will not be set on the issue. For example, if you want to set the resolution attribute in your Jelly XML then your transition MUST have a screen associated with it that includes the resolution field on that screen.

Attributes

Attribute Name

Type

Default Value

Description

user

string

Currently logged in user

Username of the user to execute the workflow transition. The user needs to have the adequate permissions to execute the transition. Please note that the permissions required also depend on the fields that are updated during the transition. (See other attributes below).

key

string

 

The key of the issue to execute the transition on.

workflowAction

string

 

The id or name of the workflow transition to execute. If the argument can be converted to a number it is assumed to be an id of the transition. Otherwise it is assumed to be a name.

resolution

string

 

The id or name of the resolution to set on the issue during the transition. Please note that the transition must expect the resolution to be updated, otherwise an error is generated if this attribute is supplied. If the argument can be converted to a number it is assumed to be an id of the resolution. Otherwise it is assumed to be a name.

assignee

string

 

The username of the user to assign an issue to during the transition. The "user" executing the transition must have permissions to assign issues if this attribute is supplied. Please note that the transition must expect the assignee to be updated, otherwise an error is generated if this attribute is supplied.
Use value "-automatic-" to let JIRA assign the issue to the default assignee.

fixVersions

string

 

A comma separated list of version ids or names to set as "fix for" versions during the transition. The "user" executing the transition must have permissions to set "fix for" versions if this attribute is supplied. Please note that the transition must expect the "fix for" versions to be updated, otherwise an error is generated if this attribute is supplied. If a value in the provided comma separated list can be converted to a number it is assumed to be an id of a version. Otherwise it is assumed to be a name.

comment

string

 

The comment to add to the issue during the transition. The "user" executing the transition must have permissions to add comments and the transition must be expecting comments to be added during its execution for the comment to be added successfully.

groupLevel

string

 

The level for the comment. The level must be a name of a group the user is a member of. NOTE: If this is specified you can not specify the roleLevel parameter.

roleLevel

string

 

Name or Id of Project Role that can see this comment. NOTE: If this is specified you can not specify the groupLevel parameter.

Examples

Execute Workflow Transition

jira:UpdateProjectRole

This tag will update the name and description for a given project role id.

Attributes

Attribute Name

Type

Default Value

Description

projectroleid

int

 

The id of the project role you want to query

name

string

 

The name you want the project role updated with

description

string

 

The description you want the project role updated with

Examples

Updating a project role

Beta Tags

There are also a number of BETA tags that have not been fully tested or documented. The following list contains the tags and the attributes that can be passed to them:

  • AddIssueSecurity
    • schemeId (required)
    • security (required)
    • type (required)
  • AddIssueSecurityLevel
    • name (required)
    • description (required)
    • Output
      • jelly.issue.scheme.level.id
  • CreateIssueSecurityScheme
    • name (required)
    • description (required)
    • Output
      • jelly.issue.scheme.id
  • LoadManager
    • var (variable to put manager in)
    • manager (name of manager e.g. IssueManager)
  • LoadProject
    • var (variable to put project in)
    • project-name (name of project)
  • RemoveGroup
    • name (required)
  • RemovePermissionScheme
    • schemeId (required)
    • confirm (required))
  • RemoveProject
    • pId (required)
  • SelectProjectScheme
    • projectKey (required)
    • permission-scheme (Name of permission scheme)or
    • issue-scheme (Name of issue security scheme)
  • StringContains
    • value (String to look in)
    • possiblyContains (String to look for)
    • doesContain (true or false) if value contains possiblyContains == doesContain, the inside of the tag is executed.

If you would like more information on how to use the Beta tags, please read the source and/or post to the Atlassian Answers for JIRA.

Sample scripts

Creating a new Project

To properly partition projects, one needs a permission scheme per project, and project-specific groups to allocate permissions to. Setting up a new project can be a time-intensive process. The following sample Jelly scripts automate this:
This script might be used for a publicly visible project:

This script is more complicated, with multiple groups per project:

For a list of projects, perform a project-specific operation.

This script iterates through a (comma-separated) list of projects, creates a project-specific group, and adds a user to that group.

Create a user, issue, and assign the issue to the user

The following script creates a user (called new-user), creates a new issue, adds the user to the jira-developers group and assigns the issue to the user. It illustrates the use of context variables.

Assigning and Starting Progress

Here we create an issue, assign it to 'bob' (who must be in jira-developers), and start progress:

Moving unreplied-to issues into an 'Inactive' state

When JIRA is used for interacting with customers, this script is useful for finding issues which are awaiting customer response, and haven't been responded to in a while. It moves such issues into an 'Inactive' state.

You would typically invoke this script periodically with the Jelly Service.

Where:

  • workflowStep is the name of a workflow transition, e.g "Close Issue", "Start Progress", just as they appear in the left-hand menu on the issue screen.
  • workflowUser is the user to run the transition as
  • filterid is the id of a saved search (filter), which finds issues needing to be inactivated (transitioned). This ID can be discovered from the filter URL on the "Manage" tab in "Find issues".

The JIRA Toolkit is useful in conjuction with this script, to find issues awaiting customer response.

34 Comments

  1. How do I update required custom field/s while doing jira:TransitionWorkflow?

    I added a custom field Root Cause (required) to my resolution screen and now my jelly script is throwing error on TransitionWorkflow.

    It happens even if the root cause has already been specified by users at earlier stage of the workflow.

  2. Workflow's Post function also has one function as update field, using this function you can update Custom field value.

    Could you please elaborate it in deep so i can try this problem?

    Thnaks,

    Dharmendra

    1. Thanks for offering to help. This is a section of my jelly script:

      Very similar to example given here on this page on jira:TransitionWorkflow. It was working find until I added a custom field (required) to the resolution screen and now I am seeing this error in the log:

      So how do I set value for a custom field while doing jira:TransitionWorkflow?

  3. Is there a maximum size to a jelly script I can run?  I'm using one to migrate tickets from Trac to JIRA.  If my script contains about 500 tickets it takes a few minutes, but the project and all the tickets get imported correctly.  If I remove the project, modify the script by just adding more tickets, and re-run, the script fails almost immediately and I get an exception from the JellyRunner (see below).  It seems to choke on trying to read in the jelly doc.

    2010-07-08 12:14:52,212 http-8018-3 ERROR cja 734x9941x1 13t1wgi some_ip_address /secure/admin/util/JellyRunner.jspa [web.action.util.JellyRunner] Could not read script string.
    java.io.IOException: expected '=', got 's'
            at electric.util.lex.Lex.readChar(Lex.java:371)
            at electric.xml.sax.SAXParser.parseAttributes(SAXParser.java:685)
            at electric.xml.sax.SAXParser.parseElement(SAXParser.java:597)
            at electric.xml.sax.SAXParser.parseChildren(SAXParser.java:787)
            at electric.xml.sax.SAXParser.parseElement(SAXParser.java:633)
            at electric.xml.sax.SAXParser.parseChildren(SAXParser.java:787)
            at electric.xml.sax.SAXParser.parseElement(SAXParser.java:633)
            at electric.xml.sax.SAXParser.parse(SAXParser.java:330)
            at electric.xml.sax.SAXParser.parse(SAXParser.java:270)
            at electric.xml.sax.SAXParser.parse(SAXParser.java:241)
            at electric.xml.sax.SAXParser.parse(SAXParser.java:207)
            at org.apache.commons.jelly.parser.XMLParser.parse(XMLParser.java:238)
            at org.apache.commons.jelly.parser.XMLParser.parse(XMLParser.java:220)
            at com.atlassian.jira.web.action.util.JellyRunner.getJellyScript(JellyRunner.java:144)
            at com.atlassian.jira.web.action.util.JellyRunner.doExecute(JellyRunner.java:87)
            at webwork.action.ActionSupport.execute(ActionSupport.java:165)
            at com.atlassian.jira.action.JiraActionSupport.execute(JiraActionSupport.java:53)
            at webwork.dispatcher.GenericDispatcher.executeAction(GenericDispatcher.java:139)
            at com.atlassian.jira.web.dispatcher.JiraServletDispatcher.service(JiraServletDispatcher.java:171)
            at javax.servlet.http.HttpServlet.service(HttpServlet.java:717)
            at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:290)
            at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
            at com.atlassian.core.filters.HeaderSanitisingFilter.doFilter(HeaderSanitisingFilter.java:44)
            at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
            at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
            at com.atlassian.plugin.servlet.filter.IteratingFilterChain.doFilter(IteratingFilterChain.java:46)
            at com.atlassian.plugin.servlet.filter.ServletFilterModuleContainerFilter.doFilter(ServletFilterModuleContainerFilter.java:55)
            at com.atlassian.plugin.servlet.filter.ServletFilterModuleContainerFilter.doFilter(ServletFilterModuleContainerFilter.java:41)
            at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
            at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
            at com.atlassian.jira.web.filters.accesslog.AccessLogFilter.executeRequest(AccessLogFilter.java:99)
            at com.atlassian.jira.web.filters.accesslog.AccessLogFilter.doFilter(AccessLogFilter.java:83)
            at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
            at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
            at com.atlassian.jira.security.xsrf.XsrfTokenAdditionRequestFilter.doFilter(XsrfTokenAdditionRequestFilter.java:50)
            at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
            at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
            at com.opensymphony.module.sitemesh.filter.PageFilter.parsePage(PageFilter.java:119)
            at com.opensymphony.module.sitemesh.filter.PageFilter.doFilter(PageFilter.java:55)
            at com.atlassian.jira.web.filters.SitemeshExcludePathFilter.doFilter(SitemeshExcludePathFilter.java:40)
            at com.atlassian.core.filters.AbstractHttpFilter.doFilter(AbstractHttpFilter.java:31)
            at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
            at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
            at com.atlassian.plugin.servlet.filter.IteratingFilterChain.doFilter(IteratingFilterChain.java:46)
            at com.atlassian.plugin.servlet.filter.ServletFilterModuleContainerFilter.doFilter(ServletFilterModuleContainerFilter.java:55)
            at com.atlassian.plugin.servlet.filter.ServletFilterModuleContainerFilter.doFilter(ServletFilterModuleContainerFilter.java:41)
            at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
            at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
            at com.atlassian.seraph.filter.SecurityFilter.doFilter(SecurityFilter.java:219)
    
  4. The problem wasn't the size of the doc. The problem was the keywords field in the trac tickets had quoted strings in them. When they were mapped to the environemnt attribute, they appeared like this in the jelly doc/script:

    environment=""User Experience",  interface"
    

    ...so the doc was malformed.

    Another issue I had was empty comments. Some trac tickets maybe had nothing in them so empty comments were created which spanned multiple lines in the jelly doc. They caused the import to fail.

  5. Anonymous

    How can I add a subtask issue? The CreateIssue tag doesn't have anything like "parentIssue".

    • Maybe I should nest CreateIssue inside CreateIssue?
    • Or maybe use LinkIssue with some special type of link?
    1. Unfortunately you cannot, see JRA-8229

  6. Anonymous

    How can I put the contents of a filter export into an output file?

  7. I want to write a Jelly script that modifies the original time estimate for some JIRA issues. It is possible to do that?

    1. Anonymous

      I need exactly the same, anyone knows if is possible?

  8. Anonymous

    Hi ,

    I want to create custom tag in jira and Run it ;my custom field should have as input Excel fiel and the tag will convert it inti csv format of JIRA .

    1-what are ths steps that i must do to obtain this? that's mean haw can i procede to create the custom tag? is't just a simple class?

    2-i have added a browse button to choose the excel file and a button submit in "introduction " through dashboard ,and i want the submit button to execute the conversion to csv ( result of jelly runner as an event of a button ) how can i proced?

    Best regards

    thank you for your help

  9. Anonymous

    Is the jira.jelly.on=true parameter needed when you only run a script as a service?

    Or is it possible to create and test your script with Jelly Runner, create a Service running the script and then disable the parameter?

  10. Hi all,

    Anyone knows how i can add a custom field that has issue type scope in a project?

    The attribute fieldscope only allows "project" or "issuetype", but not a combination of both.

    In the user interface it is possible to restrict a custom field to a issuetype within a project

    Regards,

    Dieter

  11. Anonymous

    Hi ,

    I want to create custom tag in jira and Run it ;my custom field should have as input Excel fiel and the tag will convert it inti csv format of JIRA .

    1-what are ths steps that i must do to obtain this? that's mean haw can i procede to create the custom tag? is't just a simple class?

    2-i have added a browse button to choose the excel file and a button submit in "introduction " through dashboard ,and i want the submit button to execute the conversion to csv ( result of jelly runner as an event of a button ) how can i proced?

    Best regards

    thank you for your help

  12. Anonymous

    Hi ,

    I want to create custom tag in jira and Run it ;my custom field should have as input Excel fiel and the tag will convert it inti csv format of JIRA .

    1-what are ths steps that i must do to obtain this? that's mean haw can i procede to create the custom tag? is't just a simple class?

    2-i have added a browse button to choose the excel file and a button submit in "introduction " through dashboard ,and i want the submit button to execute the conversion to csv ( result of jelly runner as an event of a button ) how can i proced?

    Best regards

    thank you for your help

  13. Hi all,

    I want to know if it is possible to set a Jelly Service that scans inside a directory to see if there is jelly scripts to be executed.

    The aim is to drop inside that directory one jelly script for each new issue we want to create.

    Using this way, we should be able to fill custom fields.

    Thank in advance,

    Regards,

    David

  14. Anonymous

    Hi,

    Can you configure a project to be a greenhopper project using a jelly script?

    Thanks,

    Rich

    1. Hello,

      I don't believe this is possible at present. Please raise your request for this functionality on the Make GreenHopper API's available to other plugins feature request.

      Thank you.

      Nicholas

  15. Hi,

    Am using JIRA 4.2.2 EAR and Tomcat 6.0.14.

    How to enable jelly in JIRA EAR?

    Please suggest.

    Thanks in advance.

  16. hi,

    How to make a custom field non -editable in edit screen once issue created. I choose the custom field type "message custom field for edit" and then named it as Banner Summary.

    What java script is required to make this readonly?

    Please suggest

    1. viswa,

      This is a JELLY page, not a custom fields page.  Hopefully the admins move this conversation elsewhere, appropriate.

      You should probably use the "Velocity processed Message Custom Field (for edit)" type. 

      Then, the script you will use should be fairly easy to write.  Something like: 

      The code is abstracted from my much more complex Velocity code, which you probably don't want anyway.

      Hopefully this helps a little.

      Luck!
      Scott

  17. What is the proper way to add a default value to a custom field?

    I found a tag AddCustomFieldDefaultValue, however it doesn't seem to function correctly in my tests.

    Is there a different tag, or a default value attribute that I should use, instead?

  18. Anonymous

    I was trying to use the createCustomField tag and kept getting "Invalid Field Type" and "Invalid Searcher". 

    The documentation gives no indication on what the appropriate values for these parameters should be.  Looking at the corresponding admin page is no help as it just shows the display name, which isn't what the tag is expecting.

    After much hair-pulling, I found that the exact values for these parameters can be found in:

    /atlassian-jira/WEB-INF/classes/system-customfieldtypes-plugin.xml

    Perhaps this can be added to the documentation.

  19. Anonymous

    hi,

    we have implemented auto escalation service by using jelly script.but we not understanding how to 'CC' to project lead  while changing workflow transition by using   <jira:TransitionWorkflow>.

    <jira:TransitionWorkflow key="$

    Unknown macro: {issue.key}

    " user="$

    Unknown macro: {workflowUser}

    " workflowAction="$

    Unknown macro: {workflowStep}

    " comment="$

    Unknown macro: {comment}

    "/>


    Please suggest!.

    regards,

    Richards

  20. Hello All,

    I wanted to add  loads of external versions to a JIRA project. I am using jelly scripts to add those versions to a projec. but as well as I wanted to add whether that version is Archieved or not.

    In the above example of add Version there is no such attribute.

    Can anyone please tell me, How to add "isArchieved" attribute to a Add Version jelly script.

    This is very urgent!!!

    Thanks in advance.

    Regards,

    Renu

  21. Hello All,

     

    For above my concern, about make version Archieved. I have written customised jelly scripts.

    But now my problem is that value is not persisting in the database. IF I make any changes  in the manage versions those versions which I have archieved using jelly script that are will become unarchieve.

    Can any one please give solution of my concern??

    Please its urgent !!!

  22. Hi Guys,

    I try to close some Issues due to a created jira-filter:

    <JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib" xmlns:core="jelly:core" xmlns:log="jelly:log" >
    <jira:Login username="user" password="password123">
        <log:info>Running Close issues service</log:info>
        <!-- Set Params -->
         <core:set var="workflowStep" value="2" />
        <core:set var="workflowUser" value="user" />
        <core:set var="filterKE" value="10301" />
        <core:set var="filterKL" value="10300" />
    
        <!-- Run the SearchRequestFilter -->
        <jira:RunSearchRequest filterid="${filterKE}" var="issuesKE" />
        <jira:RunSearchRequest filterid="${filterKL}" var="issuesKL" />
     
        <!-- Iterate over the KE issues -->
        <core:forEach var="issue" items="${issuesKE}">
            <jira:TransitionWorkflow key="${issue.key}" user="${workflowUser}" workflowAction="${workflowStep}"/>
        </core:forEach>
    
        <!-- Iterate over the KL issues -->
        <core:forEach var="issue" items="${issuesKL}">
            <jira:TransitionWorkflow key="${issue.key}" user="${workflowUser}" workflowAction="${workflowStep}"/>
        </core:forEach>
    
    </jira:Login>
    </JiraJelly>

    If I start the script manually it works well. Using the Jira-Service "Jelly-Runner": Jira complains that the workflow transition is not valid for the current workflow state.

    But I just checked that. The Isseu's-State is "open" and I just want to close?

    Any Ideas anyone?

    Best Robert

     

  23. Anonymous

    How Can I Add Issue Type using jelly Script?

     

  24. Anonymous

    Hello,

    How can I get server or JIRA instance info in Jelly script ?

    Example gethostname, JIRA application name, Home folder, .... ?

     

    Thx

     

    Michel.

     

  25. Anonymous

    When writing about "context variables" above, you mention jira:CreateUser in the paragraph, but the example uses jira:CreateIssue

  26. Anonymous

    Hi,

    I tried to run jelly script via JIRA service, but it doesn't work - nothing happened. I have my jelly scripts saved as xml file and I put them to the JIRA directory (jira/jellyscripts exactly) and then I link them in the service using URL like this: D:\jira\jellyscipts\myscript.xml.

    Did I do something wrong somewhere?

    Thanks

    Vaclav

  27. Anonymous

    Hi,

    I tried to enable jelly runner for my instance by following the steps in atlassian guide.

    Made changes in the setenv file, but still jelly runner is inactive.

    Can you please suggest the steps that need to be performed for enabling jelly runner for Jira.

    Thanks

  28. Are there plans to allow us to set the Issue Type Scheme when creating projects from Jelly? Currently we can set the permissions scheme but it would be great if we could also set the Issue Type Scheme.

  29. Anonymous

    Instead of grabbing the username for a notification, I want to grab the FullName value from a created issue.  Any suggestions?