Dynamic Forms

Use the Dynamic Forms feature to simplify the process of adding variables to your ScriptRunner Groovy scripts. Dynamic Forms allow 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 customization.

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 form annotations are available anywhere you can enter code in ScriptRunner, including the Script Console, Jobs, Listeners, Pre Hooks, Post Hooks, and Merge Checks.

For example, as a power user, you have created a script to assign reviewers for a pull request. This script is used across multiple repositories and projects, and you need to set different reviewers for each case. Instead of hardcoding the users to be used for reviewers for each case, you can now use a dynamic form annotation, meaning the users 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 centralized location. The dynamic form annotation shows the ‘reviewers’ variable as a form field:

The above example uses the following code:

import com.atlassian.bitbucket.pull.PullRequestService
import com.atlassian.sal.api.component.ComponentLocator
import com.atlassian.bitbucket.user.ApplicationUser
import com.onresolve.scriptrunner.parameters.annotation.UserPicker

@UserPicker(label = 'Reviewers', description = 'Users to review the PR', multiple = true)
List<ApplicationUser> reviewers

def pullRequestService = ComponentLocator.getComponent(PullRequestService)
def pullRequest = event.pullRequest

reviewers.each { user ->
    pullRequestService.addReviewer(pullRequest.toRef.repository.id, pullRequest.id, user.name)
}

The following dynamic form field types are available:

Name	Description	Target Type
User Picker	Field allowing user selection.	com.atlassian.bitbucket.user.ApplicationUser
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.bitbucket.project.Project
Repository Picker	Field allowing repository selection.	com.atlassian.bitbucket.repository.Repository
Branch Picker	Field allowing branch selection.	com.onresolve.scriptrunner.bitbucket.branch.BranchWithRepository implements: com.atlassian.bitbucket.repository.Branch has a reference to: com.atlassian.bitbucket.repository.Repository
Tag Picker	Field allowing branch selection.	com.onresolve.scriptrunner.bitbucket.tag.TagWithRepository implements: com.atlassian.bitbucket.repository.Tag has a reference to: com.atlassian.bitbucket.repository.Repository

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

Create a Dynamic Form

Click the Cog in the top ribbon, to open the Administration Overview page.
Select Script Console under ScriptRunner.
Write your new script in the Script field, annotating the variables you want users to provide. 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.

Navigate to your existing inline script, and add in required annotations.
Copy the script.
Use the Script Editor to open your Scripts Root folder.
Select the folder in which you want to save the script, and click the Create New File icon.
Enter a file name in the Add New Groovy File/Add New Groovy Folder window.
Click Add.
Paste your inline script into the file, and click Save. This script is now available as a file and can be shared with multiple Bitbucket users on the same instance.

Annotations

User Picker

Add a user picker field into your script.

    import com.atlassian.bitbucket.user.ApplicationUser
    import com.onresolve.scriptrunner.parameters.annotation.*
    
    @UserPicker(label = "User", description = "Select a user")
    ApplicationUser user

User multi-pickers are also supported.

    import com.atlassian.bitbucket.user.ApplicationUser
    import com.onresolve.scriptrunner.parameters.annotation.*
    
    @UserPicker(label = "Users", description = "Select users", multiple = true)
    List<ApplicationUser> users

Short Text

Add a short text field to a script.

    import com.onresolve.scriptrunner.parameters.annotation.ShortTextInput

    @ShortTextInput(label = "Branch name", description = "Enter the branch name")
    String branchName

Select List

Add a single-select list with configurable options.

    import com.onresolve.scriptrunner.parameters.annotation.Select
    import com.onresolve.scriptrunner.parameters.annotation.meta.Option
    
    @Select(
        label = "Color",
        description = "Select color",
        options = [
            @Option(label = "Green", value = "green"),
            @Option(label = "Blue", value = "blue"),
        ]
    )
    String value

Multi-select lists are also supported.

    import com.onresolve.scriptrunner.parameters.annotation.Select
    import com.onresolve.scriptrunner.parameters.annotation.meta.Option

    @Select(
        label = "Colors",
        description = "Select colors",
        options = [
            @Option(label = "Green", value = "green"),
            @Option(label = "Blue", value = "blue"),
            @Option(label = "Red", value = "red"),
        ],
        multiple = true
    )
    List<String> values

Checkbox

Add a checkbox to a script.

    import com.onresolve.scriptrunner.parameters.annotation.Checkbox
    
    @Checkbox(label = "Delete branch", description = "Select the checkbox to delete the branch")
    Boolean shouldDeleteBranch

Project Picker

Add a project picker to a script.

    import com.atlassian.bitbucket.project.Project
    import com.onresolve.scriptrunner.parameters.annotation.ProjectPicker
    
    @ProjectPicker(label = 'Project', description = 'Pick a project')
    Project project

Project multi-pickers are also supported.

    import com.atlassian.bitbucket.project.Project
    import com.onresolve.scriptrunner.parameters.annotation.ProjectPicker
    
    @ProjectPicker(label = 'Projects', description = 'Pick some projects', multiple = true)
    List<Project> projects

Repository Picker

Add a repository picker to a script.

    import com.atlassian.bitbucket.repository.Repository
    import com.onresolve.scriptrunner.parameters.annotation.RepositoryPicker
            
    @RepositoryPicker(label = 'Repository', description = 'Select a repository')
    Repository repository

Repository multi-pickers are also supported.

    import com.atlassian.bitbucket.repository.Repository
    import com.onresolve.scriptrunner.parameters.annotation.RepositoryPicker
            
    @RepositoryPicker(label = 'Repositories', description = 'Select repositories', multiple = true)
    List<Repository> repositories

Branch Picker

Add a branch picker to a script.

    import com.onresolve.scriptrunner.bitbucket.branch.BranchWithRepository
    import com.onresolve.scriptrunner.parameters.annotation.BranchPicker
    
    @BranchPicker(label = 'Branch', description = 'Select a Branch')
    BranchWithRepository branch

Tag Picker

Add a tag picker to a script.

    import com.onresolve.scriptrunner.bitbucket.tag.TagWithRepository
    import com.onresolve.scriptrunner.parameters.annotation.TagPicker
    
    @TagPicker(label = 'Tag', description = 'Select a tag')
    TagWithRepository tag