Asynchronous Functions

Asynchronous functions run after the current transaction is complete. They are supported in on-change, action, and on-schedule workflow rules, app HTTP handlers, and custom MCP tools.

The core pattern is the same in every supported script type. Differences in available context values are called out where they matter.

Use async functions for work that should not block the original operation. Common use cases include sending a request to an external service, handling the response later, delaying an update, and debouncing repeated changes.

Each async function has a name that YouTrack uses when scheduling follow-up work. To use values from the function that schedules async work, save them with ctx.store() and read them later with ctx.load().

Where You Can Use Async Functions

You can use async functions in the following script types:

Script type	Notes
On-change, action, and on-schedule workflow rules	Async functions use the same context shape as the rule action, including `ctx.issue`, `ctx.currentUser`, and requirements.
App HTTP handlers	Async functions can be scheduled from endpoints with `issue`, `project`, `article`, `user`, or `global` scope. For async HTTP response handlers, `ctx.response` represents the external service response.
Custom MCP tools	Async functions can be scheduled from the tool action. The context follows the custom MCP tool context, so it provides `ctx.arguments` but not `ctx.issue`, `ctx.article`, or `ctx.user`.

How Async Execution Works

The function that schedules async work and the async function run as separate steps.

The scheduling function calls ctx.invokeAsync() or an async HTTP method with the name of an async function.
If the transaction is completed successfully, YouTrack starts the follow-up work later as the same user.
The follow-up function receives a new ctx object based on the script type that scheduled the work.
Use ctx.store() and ctx.load() to pass short-lived values between these steps.

Async API Overview

Here are the main methods and objects you use with async functions. The table also lists ctx.response for async HTTP response handlers, where it contains the external service response.

Method or object	What it does
`asyncFunctions`	Stores named async functions. For more information, see Declare and Schedule an Async Function.
`ctx.invokeAsync()`	Schedules an async function. For more information, see Declare and Schedule an Async Function.
`ctx.store()`	Saves a value for async work. For more information, see Share State Across Async Calls.
`ctx.load()`	Reads a stored value. For more information, see Share State Across Async Calls.
`postAsync()`, `getAsync()`, and other async HTTP methods	Send an HTTP request later. For more information, see Call External Services after Transaction Completion.
`ctx.response` in async HTTP response handlers	Contains the external service response. For more information, see Call External Services after Transaction Completion.

Declare and Schedule an Async Function

Declare async functions in an asyncFunctions object in the same script object that starts the work. The object is a top-level property of the script object. Depending on the script type, place it next to properties such as action, handle, or execute.

The asyncFunctions object is a map of function names to JavaScript functions. Pass one of these names to ctx.invokeAsync() or use it as an async HTTP response handler. Inline callbacks are not supported.

The ctx.invokeAsync() method schedules a named async function for execution after the current transaction is complete. It doesn't return a value from the async function.

The method accepts the following parameters:

Parameter	Description	Required
`functionName`	A string that matches a key in the `asyncFunctions` object.	✓
`delay`	The delay before execution, in milliseconds. Default value: `0`. Maximum value: seven days.
`deduplicationKey`	A string key that lets YouTrack replace a pending async call with a newer one. When another pending call with the same key exists for the same script configuration, YouTrack deletes the old call and schedules the new one with a fresh delay. In workflow rules, the scope is a specific rule attached to a specific project. The same key in another rule or another project doesn't replace the call.

Parameter

Description

Required

functionName

A string that matches a key in the asyncFunctions object.

✓

delay

The delay before execution, in milliseconds.

Default value: 0. Maximum value: seven days.

deduplicationKey

A string key that lets YouTrack replace a pending async call with a newer one.

When another pending call with the same key exists for the same script configuration, YouTrack deletes the old call and schedules the new one with a fresh delay. In workflow rules, the scope is a specific rule attached to a specific project. The same key in another rule or another project doesn't replace the call.

The following workflow rule saves an issue summary and processes it later:

            const entities = require('@jetbrains/youtrack-scripting-api/entities');

            exports.rule = entities.Issue.onChange({
              title: 'Process issue update later',
              guard: (ctx) => ctx.issue.isChanged('summary'),
              action: (ctx) => {
                ctx.store('summary', ctx.issue.summary);
                ctx.invokeAsync('processSummary', 2000, 'summary-' + ctx.issue.id);
              },
              asyncFunctions: {
                processSummary: (ctx) => {
                  const summary = ctx.load('summary');
                  ctx.issue.addComment('Processed summary: ' + summary);
                }
              }
            });
        

Use ctx.store(key, value) before scheduling an async function or async HTTP call to persist values for the follow-up function. Use ctx.load(key) inside an async function to retrieve the value.

ctx.store() saves primitive values, null, and references to YouTrack entities, such as issues or users, in the async execution context. Stored values are persisted only when the same execution also schedules an async function or an async HTTP call.

ctx.load() is available inside async functions. It returns null when the key has not been stored.

Stored values are scoped to one async call chain and are cleaned up when the chain is complete. Use app settings or YouTrack entities for long-lived data.

ctx.store(key, value)

Saves a value for later async execution.

Parameter	Description
`key`	A string identifier for the stored value.
`value`	A primitive value, `null`, or a reference to a YouTrack entity.

ctx.load(key)

Returns a value saved with ctx.store(). Entity references are resolved back to entity objects.

Parameter	Description
`key`	A string identifier for the stored value to load.

Call External Services after Transaction Completion

The @jetbrains/youtrack-scripting-api/http module provides async variants of HTTP request methods: doAsync, getAsync, postAsync, putAsync, patchAsync, and deleteAsync.

These methods schedule the outgoing HTTP request after the current transaction is complete. Pass the name of an async function as the last argument. When YouTrack receives the response, it invokes that function and exposes the external response as ctx.response.

Async HTTP methods don't return the response to the function that calls them and don't support delayed execution. Put the response logic in the named async function.

The following workflow rule sends an HTTP request and handles the response in an async function:

            const entities = require('@jetbrains/youtrack-scripting-api/entities');
            const http = require('@jetbrains/youtrack-scripting-api/http');

            exports.rule = entities.Issue.onChange({
              title: 'Notify external service after transaction completion',
              guard: (ctx) => ctx.issue.isChanged('State'),
              action: (ctx) => {
                const connection = new http.Connection('https://api.example.com');
                connection.addHeader('Content-Type', 'application/json');
                connection.postAsync(
                  '/issue-events',
                  null,
                  {id: ctx.issue.id, state: ctx.issue.fields.State.name},
                  'onExternalResponse'
                );
              },
              asyncFunctions: {
                onExternalResponse: (ctx) => {
                  if (ctx.response.isSuccess) {
                    ctx.issue.addComment('External service accepted the update.');
                  } else {
                    console.warn('External service failed: ' + ctx.response.body);
                  }
                }
              }
            });
        

For more details about HTTP requests in workflow rules, see Using REST API Methods in JavaScript Workflows.

Execution Behavior and Limits

Use these behavior details when you decide how to split work between the scheduling function and async functions.

Aspect	Details
Transaction timing	A scheduled async function starts only after the transaction that scheduled it finishes successfully.
User	Async functions run as the same user who scheduled the async work.
Transaction scope	Each async function runs in a new transaction.
Scheduling per execution	Each function execution can schedule one async function or one async HTTP call.
Delay	The maximum delay for a scheduled async function is 7 days.
Chain length	Async functions can schedule another async function or async HTTP call to create a chain of follow-up work. The default maximum chain length is 10 async executions.
Error handling	If an async function throws an error, YouTrack stops the remaining chain for that invocation.
Cleanup	Async execution contexts that remain stale for more than two days are cleaned up automatically.

24 June 2026