Groovy Engine

Overview

The Groovy engine provides Groovy-like syntax for writing scripts in JiBrok Studio. It supports closures, GDK-style collection methods, Java date/time classes, JSON handling, and other Groovy/Java idioms. Scripts have access to the same Jira APIs as the JavaScript engine.

Select Groovy from the engine dropdown in the Script Console or script configuration to use this engine.

Note: The Groovy engine implements a Groovy-like syntax within the JiBrok sandbox. It is not a full Groovy/JVM runtime - see Sandbox Constraints and Differences from real Groovy for details.


Supported constructs

Variables and functions

// Dynamic typing with def
def name = "Hello"
def count = 42

// Type declarations
String message = "World"
int total = 0

// Functions
def greet(name) {
    return "Hello, ${name}!"
}

// Default parameters
def createIssue(summary, priority = "Medium") {
    return [summary: summary, priority: priority]
}

GString (String Interpolation)

def key = "PROJ-123"
def status = "Open"
log "Issue ${key} is ${status}"
log "Count: ${items.size()}"

// Multi-line strings
def description = """
Issue: ${key}
Status: ${status}
"""

Closures

// Basic closure
def square = { x -> x * x }
log square(5)  // 25

// Closures with multiple params
def add = { a, b -> a + b }

// it - implicit single parameter
def doubled = items.collect { it * 2 }

// Method references
def names = issues.collect { it.summary }

Ranges

def range = 1..10           // inclusive: 1 to 10
def halfOpen = 1..<10       // exclusive: 1 to 9

for (i in 1..5) {
    log i
}

// Range methods
(1..10).each { log it }
(1..10).collect { it * 2 }

Collections

// Lists
def list = [1, 2, 3, 4, 5]
def names = ["Alice", "Bob", "Charlie"]

// Maps
def map = [name: "PROJ-123", status: "Open"]
def config = ["key": value, "another": 42]

// Sets - use HashSet; `[1, 2, 3] as Set` does not produce a working set
def uniqueItems = new HashSet([1, 2, 3])

// GDK collection methods
list.each { log it }
list.collect { it * 2 }
list.findAll { it > 3 }
list.find { it > 3 }
list.any { it > 3 }
list.every { it > 0 }
list.groupBy { it % 2 == 0 ? "even" : "odd" }
list.sum()
list.unique()

Operators

// Safe navigation
def name = issue?.fields?.priority?.name

// Elvis operator
def value = input ?: "default"

// Spaceship operator (comparison)
items.sort { a, b -> a.key <=> b.key }

// Spread operator
def names = issues*.summary

// in operator
if ("bug" in labels) { log "Has bug label" }

// instanceof
if (value instanceof String) { log "Is string" }

Control flow

// if/else
if (priority == "High") {
    log "Urgent"
} else if (priority == "Medium") {
    log "Normal"
} else {
    log "Low"
}

// switch/case
switch (status) {
    case "Open":
        log "New issue"
        break
    case "In Progress":
        log "Working"
        break
    default:
        log "Other"
}

// for loops
for (item in items) {
    log item
}

for (def i = 0; i < 10; i++) {
    log i
}

// while
while (count > 0) {
    count--
}

// times, upto, downto
5.times { log "Repeat ${it}" }
1.upto(5) { log it }
5.downto(1) { log it }

Exception handling

try {
    def result = Issues.get(key)
} catch (Exception e) {
    log "Error: ${e.message}"
} finally {
    log "Done"
}

throw new RuntimeException("Something went wrong")
assert items.size() > 0 : "No items found"   // colon form only; assert x, "msg" does not parse

Classes

class IssueProcessor {
    String projectKey

    def process(issues) {
        // Always qualify fields with this. - a bare `projectKey` resolves to
        // undefined here and the method silently returns an empty list
        return issues.findAll { it.key.startsWith(this.projectKey) }
    }
}

def processor = new IssueProcessor(projectKey: "PROJ")
def filtered = processor.process(allIssues)

Java/Groovy classes

JSON handling

// Parse JSON
def slurper = new JsonSlurper()
def data = slurper.parseText('{"name": "test", "value": 42}')
log data.name  // "test"

// Generate JSON
def json = JsonOutput.toJson([name: "test", value: 42])
def pretty = JsonOutput.prettyPrint(json)
Class Methods
JsonSlurper parseText(text)
JsonOutput toJson(obj), prettyPrint(json)

Date and time

// LocalDate
def today = LocalDate.now()
def date = LocalDate.parse("2024-06-15")
def nextWeek = today.plusDays(7)
def formatted = today.format("dd/MM/yyyy")   // no MMM token - use numeric months

// LocalDateTime
def now = LocalDateTime.now()
def meeting = LocalDateTime.of(2024, 6, 15, 14, 30, 0)
log now.format("yyyy-MM-dd HH:mm")

// ZonedDateTime
def zonedNow = ZonedDateTime.now("America/New_York")
def utc = ZonedDateTime.now("UTC")

// Duration and Period
def duration = Duration.ofHours(2)
def period = Period.ofDays(30)
def between = Duration.between(start, end)

// Formatting
def fmt = DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm")
log now.format(fmt)

// Business days
log today.isBusinessDay()
def nextBizDay = today.toBusinessDay()   // weekend -> Monday

LocalDate

Class methods: now(), parse(str)

Method Description
getYear() Get year
getMonth() Get month as a Month constant (not a number)
getDayOfMonth() Get day of month
getDayOfWeek() Get day of week as a DayOfWeek constant (not a number)
plusDays(n) / minusDays(n) Add/subtract days
plusMonths(n) / minusMonths(n) Add/subtract months
plusYears(n) / minusYears(n) Add/subtract years
isAfter(other) / isBefore(other) Compare dates
isEqual(other) Check equality
format(pattern) Format with pattern
jiraDate() Format as “2024-06-15”
mediumDate() Format as “Jun 15, 2024”
fullDate() Format as “Saturday, June 15, 2024”
isBusinessDay() Is Monday-Friday?
toBusinessDay() Weekend -> Monday
startOfMonth() / endOfMonth() Month boundaries

Not available on the Groovy LocalDate: shortDate(), longDate(), plusBusinessDays(), minusBusinessDays(), startOfYear(), endOfYear(), withNextDayOfWeek(). Those exist only on the JavaScript Date wrapper.

LocalDateTime

Class methods: now(), of(year, month, day, hour, min, sec), parse(str)

Method Description
getHour() / getMinute() / getSecond() Time accessors
plusHours(n) / minusHours(n) Add/subtract hours
toLocalDate() Extract date part
shortTime() Format as “2:30 PM”
mediumDateTime() Format as “Jun 15, 2024 2:30:45 PM”
startOfDay() Start of day (midnight)

LocalDateTime does not simply inherit the whole LocalDate set - check this table before assuming a method is there. jiraDateTime(), shortDateTime(), mediumTime() and endOfDay() do not exist.

ZonedDateTime

Class methods: now(zoneId), of(y, m, d, h, mi, s, zoneId), parse(str) - a second formatter argument is accepted but ignored

Method Description
getYear(), getMonth(), getDayOfMonth() Date accessors
getHour(), getMinute(), getSecond() Time accessors
getZone() Get timezone
plusDays(n) / minusDays(n) Add/subtract days
plusHours(n) / minusHours(n) Add/subtract hours
plusMinutes(n) / minusMinutes(n) Add/subtract minutes
plusMonths(n) / minusMonths(n) Add/subtract months
isAfter(other) / isBefore(other) Compare
toLocalDate() Extract date
toLocalDateTime() Extract date-time
toInstant() Convert to Instant
format(pattern) Format with pattern

Other date/time classes

Class Static methods
Duration ofDays(n), ofHours(n), ofMinutes(n), ofSeconds(n), ofMillis(n), between(start, end)
Period ofDays(n), ofMonths(n), ofYears(n), between(start, end) - no ofWeeks(n)
Instant now(), ofEpochMilli(ms), parse(str) - no ofEpochSecond(s)
ChronoUnit DAYS, HOURS, MINUTES, SECONDS, MONTHS, YEARS - no MILLIS

Duration instance methods: toDays(), toHours(), toMinutes(), toSeconds(), toMillis(), plus(other), minus(other), abs(), isNegative(), isZero(), toString()

Period instance methods: getYears(), getMonths(), getDays(), plus(other), minus(other), isNegative(), isZero(), toString()

Instant instance methods: plusSeconds(n), isBefore(other), getEpochSecond(), toEpochMilli()

def d = Duration.ofHours(25)
println d.toDays()     // 1
println d.toHours()    // 25
println d.toString()   // PT25H

def p = Period.ofMonths(3).plus(Period.ofDays(10))
println p.getMonths()  // 3
println p.getDays()    // 10

println ChronoUnit.MONTHS.between(
    LocalDate.of(2024, 1, 1),
    LocalDate.of(2024, 6, 15)
)   // 5

| ZoneId | of(id), systemDefault(), getAvailableZoneIds() | | DateTimeFormatter | ofPattern(pattern), ISO_LOCAL_DATE, ISO_LOCAL_DATE_TIME, ISO_ZONED_DATE_TIME, ISO_INSTANT | | SimpleDateFormat | create(pattern) |

Numeric wrappers

def n = Integer.parseInt("42")
def d = Double.parseDouble("3.14")
def isDigit = Character.isDigit('5' as char)
Class Methods
Integer parseInt(str, radix), valueOf(str), MAX_VALUE, MIN_VALUE
Long parseLong(str), valueOf(str), MAX_VALUE, MIN_VALUE
Double parseDouble(str), valueOf(str), isNaN(v), isInfinite(v), isFinite(v)
Character isDigit(ch), isLetter(ch), isLetterOrDigit(ch), isUpperCase(ch), isLowerCase(ch), isWhitespace(ch), toUpperCase(ch), toLowerCase(ch)

Collections utilities

Collections.sort(myList)
Collections.reverse(myList)
Collections.frequency(myList, "item")
Collections.min(myList)
Collections.max(myList)
Class Methods
Collections sort(list), reverse(list), frequency(collection, obj), min(collection), max(collection), unmodifiableList(list), singletonList(obj), emptyList()

java.util.Arrays is not reachable from a script. The name Arrays is taken by the Script API Arrays utility, which shadows the Java class - Arrays.asList(...) fails at runtime with “Method ‘asList’ is not allowed”. Use Groovy list literals and list methods ([1, 2, 3], list.sort()) instead.

XML/HTML building and parsing

// Build XML
def builder = MarkupBuilder.create()
builder.element("root", [:], null) {
    builder.element("item", [id: "1"], "First")
    builder.element("item", [id: "2"], "Second")
}
log builder.toString()

// Parse XML
def slurper = XmlSlurper.create()
def root = slurper.parseText(xmlString)
log root.child("item").text()
log root.child("item").attr("id")

Cryptographic hashing

// Quick hash functions
def sha = Hash.sha256("my string")
def md5 = Hash.md5("my string")

// Full MessageDigest
def digest = MessageDigest.getInstance("SHA-256")
Class Methods
Hash sha256(str), sha1(str), md5(str), sha512(str)
MessageDigest getInstance(algorithm) - supports SHA-256, SHA-1, MD5, SHA-512

URL encoding

def encoded = URLEncoder.encode("hello world", "UTF-8")  // "hello+world"
def decoded = URLDecoder.decode("hello+world", "UTF-8")   // "hello world"

UUID

def id = UUID.randomUUID()
println id.toString()   // e.g. "550e8400-e29b-41d4-a716-446655440000"

Base64

def encoded = Base64.getEncoder().encodeToString("Hello World")
println encoded   // "SGVsbG8gV29ybGQ="

def decoded = Base64.getDecoder().decode(encoded)
println decoded   // "Hello World"

StringBuilder

Mutable string builder with size limits.

def sb = StringBuilder.create("Hello")
sb.append(" ").append("World")
println sb.toString()   // "Hello World"
println sb.length()     // 11

sb.insert(5, ",")
println sb.toString()   // "Hello, World"

sb.reverse()
println sb.toString()   // "dlroW ,olleH"
Method Description
StringBuilder.create(initial?) Create builder
sb.append(str) Append string (chainable)
sb.insert(index, str) Insert at position (chainable)
sb.delete(start, end) Delete range (chainable)
sb.reverse() Reverse in place (chainable)
sb.length() Current length
sb.toString() Get result string

DecimalFormat

Number formatting with patterns.

def fmt = DecimalFormat.create("#,##0.00")
println fmt.format(1234567.8)   // "1,234,567.80"

def pct = DecimalFormat.create("0.##")
println pct.format(3.14159)     // "3.14"

Optional

Java-style Optional for nullable values.

def opt = Optional.of("hello")
println opt.isPresent()     // true
println opt.get()           // "hello"
println opt.map({ it.toUpperCase() }).get()   // "HELLO"

def empty = Optional.empty()
println empty.isEmpty()     // true
println empty.orElse("default")   // "default"
Method Description
Optional.of(value) Create with non-null value
Optional.ofNullable(value) Create from nullable value
Optional.empty() Create empty
opt.isPresent() / opt.isEmpty() Check presence
opt.get() Get value (throws if empty)
opt.orElse(default) Get value or default
opt.orElseThrow(msg?) Get value or throw
opt.map(fn) Transform value
opt.filter(fn) Filter by predicate
opt.flatMap(fn) Transform returning Optional

Random

def rng = new Random()
println rng.nextInt(100)    // random 0-99
println rng.nextDouble()    // random 0.0-1.0
println rng.nextBoolean()   // true or false

GDK type methods

The Groovy engine extends standard types with GDK-style methods.

String methods

In addition to standard string methods, the Groovy engine adds:

Method Description
size() String length
contains(str) Contains substring?
padLeft(size, padding) Pad from left
padRight(size, padding) Pad from right
center(size, padding) Center in width
count(str) Count occurrences
minus(str) Remove first occurrence
plus(str) Concatenate
matches(regex) Matches pattern?
toInteger() Parse to Integer
toLong() Parse to Long
toDouble() Parse to Double
take(n) First n characters
drop(n) Skip first n characters
toList() Convert to char list
isNumber() Is numeric string?
isInteger() Is integer string?
stripIndent() Strip common indentation
stripMargin(marginChar) Strip margin characters
tokenize(delimiters) Tokenize string
readLines() Split into lines

List/array methods

GDK collection methods available on lists:

Method Description
each(closure) Iterate elements
eachWithIndex(closure) Iterate with index
collect(closure) Transform elements (map)
findAll(closure) Filter elements
find(closure) First matching element
any(closure) Any element matches?
every(closure) All elements match?
size() List size
isEmpty() Is empty?
contains(value) Contains value?
first() / last() First/last element
head() / tail() Head/rest of list
flatten() Flatten nested lists
unique() Remove duplicates
plus(list) / minus(list) Add/remove elements
intersect(list) Intersection
disjoint(list) No common elements?
sum(closure) Sum values
max(closure) / min(closure) Max/min value
count(closure) Count matching
groupBy(closure) Group by key
countBy(closure) Count by key
collectEntries(closure) Transform to map
collectMany(closure) FlatMap
inject(initial, closure) Fold/reduce
split(closure) Partition by predicate
take(n) / drop(n) First n / skip n elements
takeWhile(closure) / dropWhile(closure) Take/drop while predicate
indexed() / withIndex() Add indices
collate(size) Split into chunks
tap(closure) Apply and return self

Number methods

Method Description
abs() Absolute value
intdiv(divisor) Integer division
power(exp) Power
times(closure) Execute n times
upto(to, closure) Iterate up to value
downto(to, closure) Iterate down to value
step(to, step, closure) Step iterate
intValue() / longValue() Convert to int/long
floatValue() / doubleValue() Convert to float/double

Map methods

Method Description
each(closure) Iterate entries
collect(closure) Transform entries
findAll(closure) Filter entries
find(closure) First matching entry
any(closure) / every(closure) Test entries
get(key) / put(key, value) Access entries
getOrDefault(key, default) Get with default
remove(key) Remove entry
size() / isEmpty() Size queries
containsKey(key) / containsValue(value) Contains checks
keySet() / values() / entrySet() Views
subMap(keys) Sub-map by keys
collectEntries(closure) Transform to map
groupBy(closure) Group by key
inject(initial, closure) Fold/reduce
with(closure) Execute with map as delegate
tap(closure) Apply and return self

Closure methods

Method Description
call(...args) Invoke closure
curry(...args) Curry from left
rcurry(...args) Curry from right
ncurry(n, ...args) Curry at position n
memoize() Cache results by argument (def slow = { x -> x * 2 }.memoize())

Jira API access

All Jira APIs are available in the Groovy engine:

// Search issues
def issues = Issues.search("project = PROJ AND status = Open")

issues.each { issue ->
    log "${issue.key}: ${issue.summary}"
}

// Get and update an issue
def issue = Issues.get("PROJ-123")
issue.update([summary: "Updated title"])

// Create an issue
def newIssue = Issues.create("PROJ", "Task", [summary: "New task"])

// Use requestJira for low-level API calls
def response = requestJira("/rest/api/3/myself")
log response.displayName

// Process with closures
def highPriority = issues.findAll { it.priority == "High" }
def summaries = issues.collect { it.summary }
def grouped = issues.groupBy { it.status }

All built-in API namespaces (Issues, Users, Projects, Fields, Components, Versions, Boards, Sprints, DateUtils, CSV, Adf, Arrays, Strings, Validator, tables, queue, asyncEvent) work identically to the JavaScript engine.


Sandbox constraints

The Groovy engine runs within the same sandbox as the JavaScript engine. The same resource limits and security restrictions apply:

  • No filesystem, network, or browser API access
  • No import of arbitrary Java/Groovy packages - only the listed classes are available
  • Resource limits (execution time, loop iterations, API calls) are enforced per trigger type
  • Method whitelisting applies to all type methods
  • No JVM access, no reflection, no class loading

Differences from real Groovy

The Groovy engine implements a large subset of Groovy 4.0 on top of a JavaScript sandbox. This section lists the user-visible places where behavior differs from a stock Groovy interpreter.

What works the same as real Groovy

  • Closures: { x -> ... }, implicit it, .curry(), .rcurry(), .ncurry(), .memoize(), nested closures, capture; a two-parameter closure receives a [value, index] pair spread into its parameters (withIndex().collect { val, idx -> ... })
  • GString interpolation: "x=$x", "x=${expr.method()}", triple-quoted strings
  • Operators: Elvis ?:, safe-nav ?., spaceship <=>, ranges ../..<, spread *., **, =~, ==~, compound assignment including **=
  • Collections: collect, findAll, find, each, eachWithIndex, inject, groupBy, sort, unique, flatten, take/drop, collate, etc.
  • Groovy truth: 0, "", null, [], [:] are all falsy
  • Maps: literal [k:v], dot-access, getOrDefault, collectEntries
  • Multi-catch: catch (IOException | RuntimeException e)
  • new ClassName() for stdlib types (StringBuilder, JsonSlurper, SimpleDateFormat, DecimalFormat, HashSet, ArrayList, LinkedHashMap)
  • Qualified type names: new java.util.HashSet(...), new groovy.json.JsonSlurper()
  • Java-style exception aliases: RuntimeException, IllegalArgumentException, NullPointerException, ArithmeticException, NumberFormatException, IOException, etc.
  • Standard Java time: LocalDate, LocalDateTime, Duration, Period, ZonedDateTime, ChronoUnit, DateTimeFormatter
  • try/catch/finally, switch with range/closure/regex cases
  • Method references: 'foo'.&toUpperCase

Numerics

  • Decimal literals are BigDecimal by default - 0.1 + 0.2 == 0.3 returns true and (0.1 + 0.2).toString() returns "0.3". The same wrapper handles + - * / %, setScale, compareTo, equals, pow, signum, unscaledValue, etc. Use .doubleValue() to drop into floating-point semantics.
  • Bare integer literals stay JavaScript numbers - 42, 0xFF, 0b1010, 1_000_000. The G suffix on a decimal (3.14G) still produces a BigDecimal; on an integer the lexer treats it as decimal too (42G -> BigDecimal). For exact integer arithmetic past 2^53 use BigInteger.create(...).
  • BigInteger for values above 2^53 - 2.power(64) auto-promotes to a BigInteger wrapper (.toString() returns '18446744073709551616'). BigInteger.create(...) / BigInteger.valueOf(...) create wrappers directly; add, subtract, multiply, divide, mod, pow, abs, negate, compareTo, min, max, signum and toBigDecimal are available.
  • Divide-by-zero throws - 1.0 / 0.0 raises BigDecimal: division by zero (matching real Groovy’s ArithmeticException), not Infinity/NaN.

Syntax

  • def (a, b) = [1, 2] - Groovy multiple assignment is parsed as destructuring; semantics may diverge on nested forms.

API style (factory vs constructor)

Both forms work for most stdlib types:

  • new StringBuilder() and StringBuilder.create()
  • new HashSet([1,2,3]) and Set.create([1,2,3])
  • new SimpleDateFormat('yyyy-MM-dd') and SimpleDateFormat.create(...)
  • new groovy.json.JsonSlurper().parseText(...) and JsonSlurper.parseText(...)

Date/Time

  • LocalDate.getDayOfWeek() returns a DayOfWeek value that supports .name() ("FRIDAY"), .getValue() (1 = Monday .. 7 = Sunday) and comparison with DayOfWeek.FRIDAY; other java.time.DayOfWeek enum methods may be missing.
  • Calendar, DayOfWeek, Month and LocalTime are available in Groovy only (not in the JavaScript engine).

Casts (as Type)

  • '42' as Integer, '3.14' as Double, [['a', 1], ['b', 2]] as Map, 'abc' as char[] work.
  • [1, 2, 2] as Set does not produce a working set (size() and contains() are wrong or unavailable) - use new HashSet([1, 2, 2]).
  • .asType(Class) is not supported - use the as operator.

Metaprogramming (not supported by design)

Groovy’s metaprogramming model (Categories, AST transforms, runtime metaclass) is fundamentally incompatible with the sandbox. These features are not planned. Use the workarounds below.

Categories - use(MyCategory) { ... }

class StringCategory { static String shout(String self) { self.toUpperCase() + "!" } }
use(StringCategory) { "hello".shout() }   // not supported

Why not: a per-block dispatch layer on top of method whitelisting would add a new code path to the hot evaluation route, for marginal value in sandbox scripts - the same effect is one line away with a free function.

Workaround: call the static method directly: StringCategory.shout("hello").

AST transformations - @Delegate, @Memoized, @Immutable, @ToString, @EqualsAndHashCode

@groovy.transform.ToString class Person { String name; int age }   // not supported
class Calc { @Memoized int slow(int x) { x * 2 } }                 // not supported
class Outer { @Delegate Inner inner = new Inner() }                // not supported

Why not: AST transforms in Groovy run at compile time, before bytecode is produced. JiBrok Studio has no separate compile phase - the engine parses and evaluates in one pass on each request, so there is no post-parse transformation step to emulate annotations.

Workarounds:

  • @ToString / @EqualsAndHashCode: write String toString() { ... }, boolean equals(o) { ... }, int hashCode() { ... } by hand.
  • @Memoized: wrap the method body with a [:] cache yourself, or use a closure with .memoize() (def slow = { x -> x * 2 }.memoize()).
  • @Immutable: use final fields and a constructor that copies inputs; rely on Groovy truth and equality manually.
  • @Delegate: define forwarding methods explicitly, or compose by delegation in code.

Runtime metaclass - ExpandoMetaClass, metaClass.mixin, methodMissing, GroovyInterceptable

String.metaClass.shout = { -> delegate.toUpperCase() }    // not supported
obj.metaClass.greet = { -> "hi" }                          // not supported
class Foo { def methodMissing(name, args) { ... } }        // not supported
class Bar implements GroovyInterceptable { def invokeMethod(name, args) { ... } }  // not supported
Listener.metaClass.mixin Sayer                             // not supported

Why not: mutating built-in types at runtime (String.metaClass.X = closure) is a security and isolation problem in a multi-tenant sandbox - closures captured by one script could leak across executions. methodMissing and invokeMethod redirect every undefined call to user code, which widens the attack surface (denial of service via recursive interception) and adds dispatch checks to every property access, conflicting with the engine’s resource budget. Runtime mixin needs the same metaclass infrastructure.

Workarounds: use closures stored in variables, regular method calls, or composition. If you need dynamic dispatch, build a lookup Map<String, Closure> and invoke entries by key.

JavaScript extensions

These are extra capabilities, not Groovy parity issues: Array.isArray(...) and Array.from(...) are available as JavaScript interop and have no Groovy equivalent.


Next steps


JiBrok Studio for Jira Cloud JiBrok Studio for Jira Cloud
Release notes
Core Features
Triggers
Extensions
Data Storage
Scripting Overview
JavaScript Engine
Python Engine
Groovy Engine
Scripting API
Administration
Guides