This page last changed on Oct 05, 2009 by rosie@atlassian.com.

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

On this page:

Enabling Jelly

JIRA's Jelly support is disabled by default, as it is a potential security hazard. To enable Jelly support, 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 ....

How to set this property depends on your application server. For example, with Tomcat (JIRA standalone distribution), set the environment variable JAVA_OPTS=-Djira.jelly.on=true, or when running JIRA Standalone 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. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
  3. Under the 'Options & Settings' sub-menu in the left-hand navigation column, click the 'Jelly Runner' link.
  4. 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.

Writing a Jelly script

Scripts are generally of the form:

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<!--
    Add your own Jelly XML here
-->
</JiraJelly>

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):

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib">
<!--
    Add your own Jelly XML here
-->
</JiraJelly>

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:

<jira:CreateIssue project-key="TP" summary="Issue One" issueKeyVar="issuekey" issueIdVar="issueid"/>
          Raised issue ${issuekey} with id ${issueid}

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

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.

The list of currently available tags:

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:AddComment comment="Issue comment" issue-key="ABC-1"
groupLevel="admin-group"/>
</JiraJelly>

Create Issue and Comment

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
  <jira:CreateIssue project-key="TP" issueType="Bug" summary="Issue summary" issueKeyVar="key"/>
  <jira:AddComment issue-key="${key}" comment="A comment on ${key}"/>
</JiraJelly>
                  

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:AddComponent project-key="ABC" name="Comp 1" description="Comp 1 description"/>
</JiraJelly>

Create Component in a Project

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateProject key="ABC" name="A Project" lead="logged-in-user">
<jira:AddComponent name="Comp 1"/>
</jira:CreateProject>
</JiraJelly>

Create Component with a Component Lead

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:AddComponent project-key="ABC" name="Comp 1" description="Comp 1 with lead" componentLead="user-name"/>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib">
<jira:SelectComponentAssignees project-key="ABC" componentName="Comp 1" assigneeType="componentLead"/>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:AddUserToGroup username="new-user" group-name="new-group"/>
</JiraJelly>

Add New User to Group

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateUser username="new-user" password="password" confirm="password"
fullname="Full name" email="test@test.com">
<jira:AddUserToGroup group-name="new-group"/>
</jira:CreateUser>
</JiraJelly>

Add User to New Group

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateGroup group-name="new-group">
<jira:AddUserToGroup username="new-user"/>
</jira:CreateGroup>
</JiraJelly>

Add New User to New Group

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateUser username="new-user" password="password" confirm="password"
fullname="Full name" email="test@test.com"/>
<jira:CreateGroup group-name="new-group">
<jira:AddUserToGroup/>
</jira:CreateGroup>
</jira:CreateUser>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:AddVersion project-key="ABC" name="Ver 1"/>
</JiraJelly>

Create a Version in a Project

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateProject key="ABC" name="A Project" lead="logged-in-user">
<jira:AddVersion name="Ver 1"/>
</jira:CreateProject>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateGroup group-name="new-group"/>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
  <jira:CreateIssue project-key="TST" summary="My Issue summary" issueKeyVar="keyvar"/>
  <jira:AssignIssue key="${keyvar}" assignee="testuser"/>
</JiraJelly>

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 in WEB-INF/classes/jira-application.properties:
jira.date.picker.java.format = yyyy-MM-d
jira.date.picker.javascript.format = %Y-%m-%e
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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateIssue project-key="ABC" assignee="-1" summary="Issue summary">
<!-- other jelly tags -->
</jira:CreateIssue>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateProject key="ABC" name="A Project" lead="logged-in-user">
<jira:CreatePermissionScheme name="admin-scheme">
<jira:AddPermission permissions="Assignable,Browse,Create,Assign"
type="group"/>
<jira:SelectProjectScheme/>
</jira:CreatePermissionScheme>
<jira:CreateIssue summary="Issue summary">
<!-- other jelly tags -->
</jira:CreateIssue>
</jira:CreateProject>
</JiraJelly>

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.
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateIssue project-key="ABC" summary="Issue summary">
<jira:AddCustomFieldValue id="customfield_10000" value="field value"/>
<jira:AddCustomFieldValue name="Environment Select list" value="Windows XP"/>

<!-- For Cascading Selects : Note also that the value for cascading selects is the optionId-->
<jira:AddCustomFieldValue id="customfield_10001" value="Parent Option Id" />
<jira:AddCustomFieldValue id="customfield_10001" value="Child Option Id" key="1" />

<!-- For Version Pickers and Single Version Pickers : Note also that the value for version pickers is the versionId-->
<jira:AddCustomFieldValue id="customfield_10002" value="Version Id"/>

<!-- For Multi Selects -->
<jira:AddCustomFieldValue id="customfield_10003" value="Value 1" />
<jira:AddCustomFieldValue id="customfield_10003" value="Value 2" />

<!-- For Multi User Pickers : Note also that the value for multi user pickers is a comma separated list of users-->
<jira:AddCustomFieldValue id="customfield_10004" value="User 1,User 2" />

</jira:CreateIssue>
</JiraJelly>
Using the name attribute has been deprecated. While it will work in 3.0 its use is discouraged.

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:LinkIssue key="TST-1" linkKey="TST-2" linkDesc="duplicates"/>
</JiraJelly>

Create two issues and link them

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateIssue project-key="HSP" assignee="-1" summary="Issue summary 1" reporter="admin" issueKeyVar="issuekey1"/>
<jira:CreateIssue project-key="NDT" assignee="-1" summary="Issue summary 2" reporter="admin" issueKeyVar="issuekey2"/>
<jira:LinkIssue key="${issuekey1}" linkKey="${issuekey2}" linkDesc="duplicates"/>
</JiraJelly>

jira:TransitionWorkflow

Broken in 3.3 and 3.3.1 — see JRA-7690

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
                    <jira:TransitionWorkflow key="TST-6" user="testuser" workflowAction="Resolve issue"
                    resolution="fixed" fixVersions="version 1,version 3" assignee="-automatic-"
                    comment="Test comment" groupLevel="jira-developers" />
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateProject key="ABC" name="A Project" lead="a-user">
<!-- other jelly tags -->
</jira:CreateProject>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateUser username="new-user" password="password" confirm="password"
fullname="Full name" email="test@test.com"/>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:RemoveUser name="existing-user"/>
</JiraJelly>

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: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)

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
  <jira:CreatePermissionScheme name="New Permission Scheme">
    <jira:AddPermission group="jira-users" permissions="Browse,Create,Comment,Attach" type="group"/>
    <jira:AddPermission group="jira-developers" permissions="Move,Assignable,Link,ViewVersionControl" type="group"/>
  </jira:CreatePermissionScheme>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib">
  <jira:CreatePermissionScheme name="New Permission Scheme">
    <jira:AddPermission type="reporter" permissions="Delete, Edit"/>
  </jira:CreatePermissionScheme>
</JiraJelly>

Make projects using default permission scheme visible to certain users

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib">
  <jira:AddPermission schemeId="0" permissions="Browse" type="user" user="johnc"/>
  <jira:AddPermission schemeId="0" permissions="Browse" type="user" user="ebf"/>
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
  <jira:AddPermission schemeId="10164" type="groupCF" groupCF="customfield_10000"
                      permissions="Assign,Assignable" />
</JiraJelly>

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:Login username="misc-user" password="password">
<!-- other jelly tags -->
</jira:Login>
</JiraJelly>

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

                       
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateCustomField fieldType="cascadingselect"
fieldScope="issuetype"
fieldName="Issue cascadingselect Bug"
issueType="Bug"
description="Bank have requested Y2K fixes to be sent as an EBF."
searcher="cascadingselectsearcher"
>
<jira:AddCustomFieldSelectValue value="Parent 1" />
<jira:AddCustomFieldSelectValue value="Parent 2">
<jira:AddCustomFieldSelectValue value="Child 1" />
<jira:AddCustomFieldSelectValue value="Child 2" />
</jira:AddCustomFieldSelectValue>
<jira:AddCustomFieldSelectValue value="Parent 3" />
</jira:CreateCustomField>
</JiraJelly>
                    

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

                        
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<!-- Adds 'description' field to the 'Field Tab' on 'Default Screen' -->
<jira:AddFieldToScreen fieldId="description" screen="Default Screen" tab="Field Tab"/>

<!-- Adds 'duedate' field to same screen as above. duedate is inserted in position 1 -->
<jira:AddFieldToScreen fieldId="duedate" screen="1" tab="0" fieldPosition="1"/>
</JiraJelly>
                    

Create a new Customfield and Add it to a Screen

                        
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
<jira:CreateCustomField fieldType="cascadingselect"
fieldScope="issuetype"
fieldName="Issue cascadingselect Bug"
issueType="Bug"
description="Bank have requested Y2K fixes to be sent as an EBF."
searcher="cascadingselectsearcher"
customFieldIdVar="customField"
>
<jira:AddCustomFieldSelectValue value="Parent 1" />
<jira:AddCustomFieldSelectValue value="Parent 2">
<jira:AddCustomFieldSelectValue value="Child 1" />
<jira:AddCustomFieldSelectValue value="Child 2" />
</jira:AddCustomFieldSelectValue>
<jira:AddCustomFieldSelectValue value="Parent 3" />
</jira:CreateCustomField>

<jira:AddFieldToScreen screen="Default Screen" fieldId="${customField.getId()}"/>
</JiraJelly>
                    

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 Behaviour 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

                        
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
  <jira:AttachFile key="TST-1" filepath="/tmp/somefile" option="override"/>
</JiraJelly>
                    

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.

[GenericEntity:Issue]
[created,2007-11-01 15:51:25.0]
[summary,Testing]
[component,null]
[workflowId,12530]
[timeoriginalestimate,null]
[fixfor,null]
[type,2]
[timespent,null]
[environment,Windows]
[resolution,null]
[status,1]
[updated,2007-11-01 15:51:25.0]
[timeestimate,null]
[id,11540]
[key,TSTA-5]
[duedate,null]
[description,Test]
[project,10063]
[reporter,admin]
[security,null]
[votes,0]
[assignee,null]
[priority,3]

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

                       
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:RunSearchRequest filterid="10524" var="issues" size-var="issuecount"/>
    <core:forEach var="issue" items="${issues}">
        ${issue.key}
    </core:forEach>
</JiraJelly>

                    

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:AddActorsToDefaultProjectRole projectroleid="1" actors="fred,admin,tom" 
        actortype="atlassian-user-role-actor" />
</JiraJelly>

                    

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:AddActorsToProjectRole projectroleid="1" actors="jira-administrators,jira-users" 
        projectkey="MKY" actortype="atlassian-group-role-actor" />
</JiraJelly>
                    

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:CreateProjectRole name="lion-tamer" description="tames the lions">
        ${jelly.role.id} ${jelly.role.name} ${jelly.role.description}
    </jira:CreateProjectRole>
</JiraJelly>
                    

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:DeleteProjectRole projectroleid="1" confirm="true" />
</JiraJelly>
                    

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.


<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib" xmlns:core="jelly:core">
    <jira:GetDefaultRoleActors projectroleid="1" var="roleactors" >
        <core:forEach var="actor" items="${roleactors.users}">
            ${actor.name}
        </core:forEach>
    </jira:GetDefaultRoleActors>
</JiraJelly>

                    

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:GetProjectRole projectroleid="1" var="role" >
            ${role.name}
    </jira:GetProjectRole>
</JiraJelly>
                    

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib" xmlns:core="jelly:core">
    <jira:GetProjectRoleActors projectkey="MKY" projectroleid="1" var="roleactors" >
        <core:forEach var="actor" items="${roleactors.users}">
            ${actor.name}
        </core:forEach>
    </jira:GetProjectRoleActors>
</JiraJelly>
                    

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.

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:IsProjectRoleNameUnique name="unique name" var="isUnique" >
        ${isUnique}
    </jira:IsProjectRoleNameUnique>
</JiraJelly>
                    

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:RemoveActorsFromProjectRole projectroleid="1" 
        actors="jira-administrators, jira-users" projectkey="MKY"
        actortype="atlassian-group-role-actor" />
</JiraJelly>
                    

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:RemoveActorsFromDefaultProjectRole projectroleid="1" 
        actors="jira-administrators, jira-users" actortype="atlassian-group-role-actor" />
</JiraJelly>
                    

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
    <jira:UpdateProjectRole projectroleid="123" name="unique name" 
        description="my project role is nice" />
</JiraJelly>
                    

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 JIRA Development Forum.

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:

<?xml version="1.0"?>
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib" xmlns:j="jelly:core">

  <j:set var="name" value="Test Project"/>
  <j:set var="key" value="TEST"/>
  <j:set var="lowerkey" value="test"/>
  <j:set var="lead_username" value="joe"/>
  <j:set var="lead_password" value="joe"/>
  <j:set var="lead_fullname" value="Joe Bloggs"/>
  <j:set var="lead_email" value="joe@example.com"/>
  <j:set var="url" value="http://example.com/TestProj"/>

  <jira:CreateUser username="${lead}" password="${lead}" confirm="${lead}" 
    fullname="${lead_fullname}" email="${lead_email}"/>
  <jira:CreateGroup group-name="${lowerkey}-developers">
    <jira:AddUserToGroup username="${lead}"/>
  </jira:CreateGroup>

  <jira:CreateProject key="${key}" name="${name}" url="${url}" lead="${lead}">
    <jira:CreatePermissionScheme name="${name} permissions">
      <jira:AddPermission type="reporter" permissions="Close"/>
      <jira:AddPermission group="jira-administrators" permissions="Close,Delete" type="group"/>
      <jira:AddPermission group="jira-users" permissions="Create,Edit,Comment,Link,Attach" type="group"/>
      <jira:AddPermission group="${lowerkey}-developers" 
        permissions="Project,ScheduleIssue,Move,Assign,Assignable,Resolve,Close,Work" type="group"/>
      <jira:AddPermission group="Anyone" permissions="Browse,ViewVersionControl"/>
      <jira:SelectProjectScheme/>
    </jira:CreatePermissionScheme>
  </jira:CreateProject>
</JiraJelly>

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

<?xml version="1.0"?>
<!-- This script handles some of the administrative chores required when adding
a new project to JIRA. It creates the project, groups, permission scheme, and gives
groups the relevant permissions in the permission scheme. -->
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib" xmlns:j="jelly:core">

<!-- Name of the project to create -->
<j:set var="name" value="Jelly Test Project"/>
<!-- Key for the new project -->
<j:set var="key" value="TEST"/>
<!-- Existing user who will become the project lead (default assignee) -->
<j:set var="admin" value="admin"/>

<jira:CreateGroup group-name="${key}-users"/>
<jira:CreateGroup group-name="${key}-developers"/>
<jira:CreateGroup group-name="${key}-managers"/>
<jira:CreateGroup group-name="${key}-bizusers"/>
<jira:CreateGroup group-name="${key}-qa"/>

<jira:CreateProject key="${key}" name="${name}" lead="${admin}">
<jira:CreatePermissionScheme name="${key} Permission Scheme">
<jira:AddPermission type="reporter" permissions="Edit"/>
<jira:AddPermission type="assignee" permissions="Resolve"/>
<jira:AddPermission group="jira-administrators" permissions="Project,Delete" type="group"/>
<jira:AddPermission group="${key}-users" permissions="Browse,Create,Comment,Attach" type="group"/>
<jira:AddPermission group="${key}-developers" permissions="Move,Assignable,Link,ViewVersionControl"
    type="group"/>
<jira:AddPermission group="${key}-managers" permissions="Edit,Assign,Assignable,Resolve,Close,Delete"
    type="group"/>
<jira:AddPermission group="${key}-bizusers" permissions="Assignable" type="group"/>
<jira:AddPermission group="${key}-qa" permissions="Assignable" type="group"/>
<jira:AddPermission group="opsmgrs" permissions="Browse,Edit,Assignable,Comment" type="group"/>
<jira:AddPermission group="dba-user-group" permissions="Browse,Assign,Assignable,Comment" type="group"/>
<jira:AddPermission group="help-desk-group" permissions="Browse,Assign,Assignable,Comment" type="group"/>
<jira:AddPermission group="webadmin-group" permissions="Browse,Assign,Assignable,Comment" type="group"/>
<jira:AddPermission group="unix-admin-group" permissions="Browse,Assign,Assignable,Comment" type="group"/>
<jira:SelectProjectScheme/>
</jira:CreatePermissionScheme>
</jira:CreateProject>
</JiraJelly>

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.

<?xml version="1.0"?>
<!-- Jelly script to create 'support' group per project -->
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib" xmlns:util="jelly:util" xmlns:j="jelly:core">
<util:tokenize var="projects" delim=",">ARM,QWI,DWI,DBOR,DBSQ,LYX,MMM,MOI,TPAI,SEP,AMR,SLA,TP,TRBC,YRD</util:tokenize>
<j:forEach var="proj" items="${projects}">
<jira:CreateGroup group-name="${proj}-support"/>
<jira:AddUserToGroup username="jeff" group-name="${proj}-support"/>
</j:forEach>
</JiraJelly>
                    

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.

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">

<jira:CreateUser username="new-user" password="password" confirm="password" 
    fullname="Full name" email="test@test.com"/>
Username is ${jelly.new.username}
 <jira:CreateIssue project-key="TP" summary="New issue summary" issueKeyVar="ik"/>
 <jira:AddUserToGroup username="new-user" group-name="jira-developers"/>
 <jira:AssignIssue key="${ik}" assignee="${jelly.new.username}"/>

</JiraJelly>

Assigning and Starting Progress

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

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">

 <jira:CreateIssue project-key="TP" summary="New issue" issueKeyVar="ik"/>
 <jira:AssignIssue key="${ik}" assignee="bob"/>
 <jira:TransitionWorkflow key="${ik}" user="bob" workflowAction="Start Progress" />
</JiraJelly>

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.

<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.enterprise.JiraTagLib" xmlns:core="jelly:core" xmlns:log="jelly:log" >
<jira:Login username="customersupport" password="XXXXXX">
        <log:warn>Running Inactivate issues service</log:warn>
        <core:set var="comment">This issue has not been updated for 5 business days.

If you have an update, please use "Add Comments For Vendor" action to let us know. 
If you need more time to gather information please let us know and we will 'freeze' this issue. 
If you have no other questions, please Close this issue.

If no update is received in the next 5 business days, this issue will be automatically closed.

Thank you,

  The Support Team</core:set>
        <core:set var="workflowStep" value="Mark Inactive" />
        <core:set var="workflowUser" value="customersupport" />

        <!-- Run the SearchRequestFilter -->
        <jira:RunSearchRequest filterid="11505" var="issues" />

        <core:forEach var="issue" items="${issues}">
                <log:warn>Inactivating issue ${issue.key}</log:warn>
                <jira:TransitionWorkflow key="${issue.key}" user="${workflowUser}" workflowAction="${workflowStep}" comment="${comment}"/>
        </core:forEach>
</jira:Login>
</JiraJelly>

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.

Document generated by Confluence on Oct 06, 2009 00:26