Use the Dynamic Forms feature to simplify the process of adding variables to your ScriptRunner Groovy scripts. Dynamic Forms allows you to create complex scripts with flexible variables that can be shared with multiple users, allowing one script to be used for various use cases.

Inline scripts are often copied and pasted, with minor changes made for different use cases. This approach requires maintenance for each usage of the script. Using Dynamic Forms, create flexible scripts with annotated variables that can be stored as files, reducing maintenance requirements while allowing for script customisation.

Annotate your variables to have them appear as form fields when a user edits a script. These annotations allow variable values within a script to be changed easily by those with limited code familiarity.

Dynamic forms annotations are available anywhere you can enter code in ScriptRunner, including the Script Console, Conditions, Validators, Post Functions, Behaviours, and many more.

For example, as a power user, you have created a script to delete issues within a project with a specific assignee. This script is used across multiple locations, varying by one variable (User) for each use case. Instead of hardcoding the User variable, you can now use a dynamic form annotation, meaning the user can be changed without needing to re-write the script. As well as being able to edit the script quickly, you can maintain the code in one centralised location. The dynamic form annotation shows the User variable as a form field:

100%

The above example uses the following code:

import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.issue.search.SearchProvider
import com.atlassian.jira.jql.parser.JqlQueryParser
import com.atlassian.jira.user.ApplicationUser
import com.atlassian.jira.web.bean.PagerFilter
import com.onresolve.scriptrunner.parameters.annotation.UserPicker

@UserPicker(label = "Assignee", description = "Issues with this assignee will be permanently deleted")
ApplicationUser user

// issues returned from that JQL will get deleted
final String searchQuery = "assignee = $user.name"

def jqlQueryParser = ComponentAccessor.getComponent(JqlQueryParser)
def searchProvider = ComponentAccessor.getComponent(SearchProvider)
def loggedInUser = ComponentAccessor.jiraAuthenticationContext.loggedInUser
def issueService = ComponentAccessor.issueService
def query = jqlQueryParser.parseQuery(searchQuery)
def searchResults = searchProvider.search(query, loggedInUser, PagerFilter.unlimitedFilter)

searchResults.getIssues().each { issue ->
    def deleteValidationResult = issueService.validateDelete(loggedInUser, issue.id)
    assert deleteValidationResult.isValid(): deleteValidationResult.errorCollection

    def deleteResult = issueService.delete(loggedInUser, deleteValidationResult)
    assert deleteResult
}

The following dynamic form field types are available:

Name Description Target Type

User Picker

Field allowing user selection.

com.atlassian.jira.user.ApplicationUser

Field Picker

Field to select any system or custom field.

com.atlassian.jira.issue.fields.Field

Short Text

Field allowing a short text input.

String

Select List

Single-select list field.

String

Checkbox

A checkbox field.

Boolean

Project Picker

Field allowing project selection.

com.atlassian.jira.project.Project

Priority Picker

Field allowing priority selection.

com.atlassian.jira.issue.priority.Priority

Issue Type Picker

Field allowing issue type selection.

com.atlassian.jira.issue.issuetype.IssueType

Issue Link Type Picker

Field allowing issue link type selection.

com.atlassian.jira.issue.link.IssueLinkType

Project Role Picker

Field allowing project role selection.

com.atlassian.jira.security.roles.ProjectRole

Group Picker

Field allowing group selection.

com.atlassian.crowd.embedded.api.Group

Saved Filter Picker

Field allowing saved filter selection.

com.atlassian.jira.issue.search.SearchRequest

Issue Status Picker

Field allowing status selection.

com.atlassian.jira.issue.status.Status

Custom Field Picker

Field allowing custom field selection.

com.atlassian.jira.issue.fields.CustomField

Resolution Picker

Field allowing resolution selection.

com.atlassian.jira.issue.resolution.Resolution

We are in the process of adding more dynamic form field types.

Create a Dynamic Form

  1. Click the Cog in the top ribbon, and open the Add-ons page.

  2. Select Script Console under ScriptRunner.

  3. Write your new script in the Script field, annotating the variables you want users to provide (see the Examples section below). Annotating variables allows them to be edited depending on requirements when running the script. These variables show as editable fields above the Script Console.

Transforming an Existing Inline Script

To enable sharing of annotated scripts, all inline scripts must be saved as files.

  1. Navigate to your existing inline script, and add in required annotations.

  2. Copy the script.

  3. Use the Script Editor to open your Scripts Root folder.

  4. Select the folder in which you want to save the script, and click the Create New File icon.

  5. Enter a file name in the Add New Groovy File/Add New Groovy Folder window.

  6. Click Add.

  7. Paste your inline script into the file, and click Save. This script is now available as a file and can be shared with multiple Jira users on the same instance.

Annotations

User Picker

Add a username picker field into your script.

import com.atlassian.jira.user.ApplicationUser
import com.onresolve.scriptrunner.parameters.annotation.*

@UserPicker(label = "User", description = "Select a user")
ApplicationUser user

Field Picker

Add a field picker into your script. The field picker lets you pick from any fields (system or custom).

import com.atlassian.jira.issue.fields.Field
import com.onresolve.scriptrunner.parameters.annotation.*

@FieldPicker(label = "Field", description = "Select a field")
Field field

Short Text

Add a short text field to a script.

import com.onresolve.scriptrunner.parameters.annotation.*

@ShortTextInput(label = "Summary", description = "Enter a short issue summary")
String issueSummaryTextInput

Select List

Add a single-select list with configurable options.

import com.onresolve.scriptrunner.parameters.annotation.*
import com.onresolve.scriptrunner.parameters.annotation.meta.*

@Select(
    label = "Color",
    description = "Select color",
    options = [
        @Option(label = "Green", value = "green"),
        @Option(label = "Blue", value = "blue"),
    ]
)
String value

Checkbox

Add a checkbox to a script.

import com.onresolve.scriptrunner.parameters.annotation.*

@Checkbox(label = "Clone project", description = "Select the checkbox to clone project")
Boolean projectShouldBeCloned

Project Picker

Add a project picker to a script.

import com.atlassian.jira.project.Project
import com.onresolve.scriptrunner.parameters.annotation.ProjectPicker

@ProjectPicker(label = 'Project', description = 'Pick a project')
Project project

Priority Picker

Add a priority picker to a script.

import com.atlassian.jira.issue.priority.Priority
import com.onresolve.scriptrunner.parameters.annotation.PriorityPicker

@PriorityPicker(label = 'Priority', description = 'Pick a priority', placeholder = 'Pick a priority')
Priority priority

Issue Type Picker

Add an issue type picker to a script.

import com.atlassian.jira.issue.issuetype.IssueType
import com.onresolve.scriptrunner.parameters.annotation.IssueTypePicker

@IssueTypePicker(label = 'Issue type', description = 'Pick an issue type', placeholder = 'Select issue type')
IssueType issueType

Add an issue link type picker to a script.

import com.atlassian.jira.issue.link.IssueLinkType
import com.onresolve.scriptrunner.parameters.annotation.IssueLinkTypePicker

@IssueLinkTypePicker(label = 'Issue link type', description = 'Pick an issue link type', placeholder = 'Pick an issue link type')
IssueLinkType issueLinkType

Project Role Picker

Add a project role picker to a script.

import com.atlassian.jira.security.roles.ProjectRole
import com.onresolve.scriptrunner.parameters.annotation.ProjectRolePicker

@ProjectRolePicker(label = 'Project role', description = 'Project role picker')
ProjectRole projectRole

Group Picker

Add a group Picker to a script.

import com.atlassian.crowd.embedded.api.Group
import com.onresolve.scriptrunner.parameters.annotation.GroupPicker

@GroupPicker(label = 'Group', description = 'Pick a group', placeholder = 'Pick a group')
Group group

Saved Filter Picker

Add a saved filter to a script.

import com.atlassian.jira.issue.search.SearchRequest
import com.onresolve.scriptrunner.parameters.annotation.SavedFilterPicker

@SavedFilterPicker(label = "Saved Filter", description = "Pick a saved filter", placeholder = "Pick a saved filter")
SearchRequest searchRequest

Issue Status Picker

Add a status to a script.

import com.atlassian.jira.issue.status.Status
import com.onresolve.scriptrunner.parameters.annotation.IssueStatusPicker

@IssueStatusPicker(label = 'Status', description = 'Pick a status', placeholder = 'Pick a status')
Status status

Custom Field Picker

Add a custom field picker to a script.

import com.atlassian.jira.issue.fields.CustomField
import com.onresolve.scriptrunner.parameters.annotation.CustomFieldPicker

@CustomFieldPicker(label = 'Custom Field', description = 'Pick a custom field', placeholder='Select custom field')
CustomField customField

Resolution Picker

Add a resolution to a script.

import com.atlassian.jira.issue.resolution.Resolution
import com.onresolve.scriptrunner.parameters.annotation.ResolutionPicker

@ResolutionPicker(label = 'Resolution', description = 'Pick a resolution', placeholder = 'Pick a resolution')
Resolution resolution

Examples

Create an Issue

The following example shows the use of dynamic form annotations in a script which creates a new issue. A short text annotator is used for Project Key and Summary, select list annotator for Issue Type and Priority, and user picker for User.

import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.user.ApplicationUser
import com.onresolve.scriptrunner.parameters.annotation.Select
import com.onresolve.scriptrunner.parameters.annotation.ShortTextInput
import com.onresolve.scriptrunner.parameters.annotation.UserPicker
import com.onresolve.scriptrunner.parameters.annotation.meta.Option

@ShortTextInput(description = "Project key", label = "Project")
String projectKey

@Select(
    description = "The issue type for the new issue",
    label = "Issue type",
    options =
        [
            @Option(label = "Bug", value = "Bug"),
            @Option(label = "Story", value = "Story")
        ]
)
String issueTypeName

@Select(
    description = "The priority of the new issue",
    label = "Priority",
    options =
        [
            @Option(label = "Major", value = "Major"),
            @Option(label = "Minor", value = "Minor")
        ]
)
String priorityName

@UserPicker(label = "User", description = "User with that user key will be the reporter of the issue")
ApplicationUser user
def reporterKey = user.name

@ShortTextInput(description = "The summary for the new issue", label = "Summary")
String summary

def issueService = ComponentAccessor.issueService
def constantsManager = ComponentAccessor.constantsManager
def loggedInUser = ComponentAccessor.jiraAuthenticationContext.loggedInUser
def project = ComponentAccessor.projectManager.getProjectObjByKey(projectKey)
assert project: "Could not find project with key  $projectKey"

def issueType = constantsManager.allIssueTypeObjects.findByName(issueTypeName)
assert issueType: "Could not find issue type with name  $issueTypeName"

// if we cannot find user with the specified key or this is null, then set as a  reporter the logged in user
def reporter = ComponentAccessor.userManager.getUserByKey(reporterKey) ?: loggedInUser

// if we cannot find the priority with the given name or if this is null, then set the default priority
def priority = constantsManager.priorities.findByName(priorityName) ?: constantsManager.defaultPriority
def issueInputParameters = issueService.newIssueInputParameters().with {
    setProjectId(project.id)
    setIssueTypeId(issueType.id)
    setReporterId(reporter.key)
    setSummary(summary)
    setPriorityId(priority.id)
}
def validationResult = issueService.validateCreate(loggedInUser, issueInputParameters)
assert validationResult.isValid(): validationResult.errorCollection

def result = issueService.create(loggedInUser, validationResult)
assert result.isValid(): result.errorCollection

"New issue key: $result.issue.key"
create an issue example

Change Issue Priority

The following example shows the use of dynamic form annotations in a script that changes the priority of an issue. A short text annotator is used for the Issue Key field, select list annotator for Priority, and checkbox annotator for Send Email.

import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.event.type.EventDispatchOption
import com.onresolve.scriptrunner.parameters.annotation.Checkbox
import com.onresolve.scriptrunner.parameters.annotation.Select
import com.onresolve.scriptrunner.parameters.annotation.ShortTextInput
import com.onresolve.scriptrunner.parameters.annotation.meta.Option

@ShortTextInput(description = "The key of the issue to be updated", label = "Issue Key")
String issueKey

@Select(
    description = "The name of the priority to set",
    label = "Priority",
    options =
        [
            @Option(label = "High", value = "High"),
            @Option(label = "Medium", value = "Medium"),
            @Option(label = "Low", value = "Low")
        ]
)
String priorityName

@Checkbox(description = "Check to send notification email", label = "Send Email")
boolean sendMail

def issueService = ComponentAccessor.issueService
def loggedInUser = ComponentAccessor.jiraAuthenticationContext.loggedInUser
def issue = ComponentAccessor.issueManager.getIssueByCurrentKey(issueKey)
def availablePriorities = ComponentAccessor.constantsManager.priorities
def priority = availablePriorities.find { it.name == priorityName }
def issueInputParams = issueService.newIssueInputParameters()
issueInputParams.with {
    priorityId = priority.id
}
def updateValidationResult = issueService.validateUpdate(loggedInUser, issue?.id, issueInputParams)
assert updateValidationResult.isValid(): updateValidationResult.errorCollection

def updateResult = issueService.update(loggedInUser, updateValidationResult, EventDispatchOption.ISSUE_UPDATED, sendMail)
"Issue priority changed to: $updateResult.issue.priority.name"
change priority example

Have questions? Visit the Atlassian Community to connect, share, and learn with other Atlassian users and experts, including Adaptavist staff.

Ask a question about ScriptRunner for JIRA, Bitbucket Server, or Confluence.

Want to learn more? Check out courses on Adaptavist Learn, an online platform to onboard and train new users for Atlassian solutions.