Part of the Scripting API reference.
The asyncEvent variable allows scripts to trigger other scripts asynchronously via Forge Queue. All methods are async.
Methods
| Method | Description |
|---|---|
asyncEvent.push(scriptId, payload?, options?) |
Push an event to another script |
asyncEvent.pushSelf(payload?, options?) |
Push an event to the current script |
Parameters
asyncEvent.push(scriptId, payload?, options?)
| Parameter | Type | Required | Description |
|---|---|---|---|
scriptId |
string | Yes | UUID of the target script |
payload |
object | No | JSON-serializable object (max 100KB) |
options |
object | No | See options below |
asyncEvent.pushSelf(payload?, options?)
Same as push() but targets the current script. Not available in Console - requires a saved script.
Options
| Option | Type | Description |
|---|---|---|
issueKey |
string | Issue key in PROJ-123 format, passed as context |
delayInSeconds |
number | Delay before processing (0-900, max 15 minutes) |
Return value
Both methods return { jobId: string }.
event Variable
When a script runs via an async event trigger, the event variable contains:
| Property | Type | Description |
|---|---|---|
event.payload |
object | Data passed by the sender (empty object if not provided) |
event.source |
string | "script" |
event.pushedBy |
string | Account ID of the sender |
event.pushedAt |
number | Timestamp in milliseconds |
event.scriptId |
string | UUID of the current script |
event.issueKey |
string/null | Issue key or null |
event.depth |
number | Chain depth: 1 for an event pushed by push/pushSelf, 0 for a scheduled delivery |
event.chainId |
string | UUID identifying the event chain (for tracing) |
Scheduled per-issue runs
Scheduled triggers share this delivery path, so the same event object is present when a scheduled script runs. There event.source is "scheduled" and event.pushedBy is the script’s actor.
If the scheduled trigger has a JQL configured, the script runs once per matching issue and the issue is bound just like it is for an event trigger:
| Binding | Description |
|---|---|
issue |
The issue object |
context.issue |
Raw issue JSON from the Jira REST API |
issueKey |
The issue key, e.g. "PROJ-123" |
event.issueKey |
Same key |
// Scheduled trigger, JQL: project = SUP AND labels = stale
log(`${event.source} run for ${issueKey}: ${issue.fields.summary}`)
Without a JQL, a scheduled trigger runs once per tick and issue / context.issue are not bound (event.issueKey is null).
Per-issue delivery is at-least-once - the same issue can be delivered twice across ticks, so keep side effects idempotent. See Run once per issue (JQL) for the paging and delta semantics.
Examples
// Push event to another script
const result = asyncEvent.push(
"550e8400-e29b-41d4-a716-446655440000",
{action: "process", itemId: 42}
)
log(result.jobId)
// Push with delay and issue context
asyncEvent.push(
"550e8400-e29b-41d4-a716-446655440000",
{action: "cleanup"},
{issueKey: "PROJ-123", delayInSeconds: 60}
)
// Hand the rest of the work to a second, asynchronous pass.
// This is a single hop: the pass it starts cannot push again.
asyncEvent.pushSelf({step: 2, batch: nextBatch})
// The script needs an Async Event trigger; not available in Console.
// Check again later (delayed follow-up)
asyncEvent.pushSelf(
{checkAgain: true},
{delayInSeconds: 300} // run in 5 minutes
)
One hop only. The maximum chain depth is 1, and a script that is itself running from an async event cannot push another one -
push()andpushSelf()throw there. Retry loops and multi-step chains built on repeatedpushSelf()calls do not work. For work that needs many steps, use Scenarios (step,loop,batch) or a scheduled trigger that drains a queue.
Target script example
// This script has an asyncEvent trigger enabled
log("Source:", event.source)
log("Payload:", event.payload)
if (event.issueKey) {
const issue = Issues.get(event.issueKey)
log("Processing issue:", issue.summary)
}
// event.depth is 1 here: this run cannot push further async events
// (asyncEvent.push / pushSelf throw "chain depth limit reached")
log("Depth:", event.depth)
Setup
- Save a script in the Library
- Go to Config tab - Triggers
- Add Trigger - select Async Event
- Optionally add a description
- Save the script
The async event trigger must be enabled for the script to receive events. Events sent to scripts without an enabled trigger are discarded.
Limits
| Limit | Value |
|---|---|
Max push/pushSelf calls per execution |
10 |
| Max payload size | 100KB |
| Max delay | 900 seconds (15 minutes) |
| Max chain depth | 1 (one hop: a script run by an async event cannot push further events) |
| Max trigger description | 2,000 characters |
See Limits for all system limits.
Notes
- Async events are globally controlled via the
async_eventtoggle in Administration - Script execution errors are not retried (only infrastructure errors trigger retries)
- The trigger is a singleton - one async event trigger per script
- Payload must be a plain JSON object (no arrays, no
__proto__/constructor/prototypekeys) pushSelfis not available in Console execution- Chain depth protection: events carry a
depthcounter that increments on each hop. A script that was itself started by an async event (event.depth= 1) cannot push further events -push/pushSelfthrowasyncEvent: chain depth limit reached (max 1). This prevents infinite loops (e.g. A callspushSelf, or A pushes to B which pushes back to A). ThechainIdidentifies the chain for tracing - Worst case per execution: 10 pushes, each starting one async run that cannot push further
- Scheduled runs (
event.source="scheduled", depth 0) are not part of a chain and can push async events
Next steps
- Async Trigger - Trigger configuration
- Scheduled Triggers - Scheduled runs and per-issue JQL delivery
- Scripting API: Queues - Message Queue operations
- Scripting API - API overview
