Atlassian: Transition issue

← Issues operations · Get started

Operation atlassian.dotransition

Provider route: POST /{cloudId}/rest/api/3/issue/{issueIdOrKey}/transitions. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/atlassian with npm, or alter-sdk-atlassian with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { AtlassianIntegration } from "@alter-ai/atlassian";

async function execute(input: Parameters<AtlassianIntegration["issues"]["doTransition"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new AtlassianIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.issues.doTransition(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_atlassian import AtlassianIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = AtlassianIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.issues.do_transition(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.cloudId	string	Required within parent	Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
path.issueIdOrKey	string	Required within parent
body	Model	Required within parent	Expand Edit issue — request body — body

Referenced models: Edit issue — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	null	Root

Schemas

7 more schemas are linked from the tables above, on the schema pages.

Edit issue — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Details of an issue update request. Additional keys: allowed
fields	object	Optional	List of issue screen fields to update, specifying the sub-field to update and its value for each field. This field provides a straightforward option when setting a sub-field. When multiple sub-fields or other operations are required, use `update`. Fields included in here cannot be included in `update`. Additional keys: see wildcard field
fields.*	JSON	Additional keys
historyMetadata	Model	Optional	Expand Edit issue — request body — body history Metadata Additional issue history details.
properties	array	Optional	Details of issue properties to be add or update.
properties[]	Model	Each item	Expand Edit issue — request body — body properties item
transition	Model	Optional	Expand Edit issue — request body — body transition Details of a transition. Required when performing a transition, optional when creating or editing an issue.
update	object	Optional	A Map containing the field field name and a list of operations to perform on the issue screen field. Note that fields included in here cannot be included in `fields`. Additional keys: see wildcard field
update.*	array	Additional keys
update.*[]	Model	Each item	Expand Edit issue — request body — body update value item

Referenced models: Edit issue — request body — body properties item, Edit issue — request body — body update value item, Edit issue — request body — body history Metadata, Edit issue — request body — body transition

Edit issue — request body — body properties item

Field	Type	Presence	Description and constraints
$	object	Root	An entity property, for more information see [Entity properties](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/). Additional keys: not allowed
key	string	Optional	The key of the property. Required on create and update.
value	JSON	Optional	The value of the property. Required on create and update.

Edit issue — request body — body update value item

Field	Type	Presence	Description and constraints
$	object	Root	Details of an operation to perform on a field. Additional keys: not allowed
add	JSON	Optional	The value to add to the field.
copy	JSON	Optional	The field value to copy from another issue.
edit	JSON	Optional	The value to edit in the field.
remove	JSON	Optional	The value to removed from the field.
set	JSON	Optional	The value to set in the field.

Edit issue — request body — body history Metadata

Field	Type	Presence	Description and constraints
$	object	Root	Details of issue history metadata. Additional keys: allowed
activityDescription	string	Optional	The activity described in the history record.
activityDescriptionKey	string	Optional	The key of the activity described in the history record.
actor	Model	Optional	Expand Edit issue — request body — body history Metadata actor Details of the user whose action created the history record.
cause	Model	Optional	Expand Edit issue — request body — body history Metadata actor Details of the cause that triggered the creation the history record.
description	string	Optional	The description of the history record.
descriptionKey	string	Optional	The description key of the history record.
emailDescription	string	Optional	The description of the email address associated the history record.
emailDescriptionKey	string	Optional	The description key of the email address associated the history record.
extraData	object	Optional	Additional arbitrary information about the history record. Additional keys: see wildcard field
extraData.*	string	Additional keys
generator	Model	Optional	Expand Edit issue — request body — body history Metadata actor Details of the system that generated the history record.
type	string	Optional	The type of the history record.

Referenced models: Edit issue — request body — body history Metadata actor

Edit issue — request body — body transition

Field	Type	Presence	Description and constraints
$	object	Root	Details of an issue transition. Additional keys: allowed
expand	string	Optional	Expand options that include additional transition details in the response. Read only: true
fields	object	Optional	Details of the fields associated with the issue transition screen. Use this information to populate `fields` and `update` in a transition request. Read only: true Additional keys: see wildcard field
fields.*	Model	Additional keys	Expand Edit issue — request body — body transition fields value
hasScreen	boolean	Optional	Whether there is a screen associated with the issue transition. Read only: true
id	string	Optional	The ID of the issue transition. Required when specifying a transition to undertake.
isAvailable	boolean	Optional	Whether the transition is available to be performed. Read only: true
isConditional	boolean	Optional	Whether the issue has to meet criteria before the issue transition is applied. Read only: true
isGlobal	boolean	Optional	Whether the issue transition is global, that is, the transition is applied to issues regardless of their status. Read only: true
isInitial	boolean	Optional	Whether this is the initial issue transition for the workflow. Read only: true
looped	boolean	Optional
name	string	Optional	The name of the issue transition. Read only: true
to	Model	Optional	Expand Edit issue — request body — body transition to Details of the issue status after the transition. Read only: true

Referenced models: Edit issue — request body — body transition fields value, Edit issue — request body — body transition to

Edit issue — request body — body history Metadata actor

Field	Type	Presence	Description and constraints
$	object	Root	Details of user or system associated with a issue history metadata item. Additional keys: allowed
avatarUrl	string	Optional	The URL to an avatar for the user or system associated with a history record.
displayName	string	Optional	The display name of the user or system associated with a history record.
displayNameKey	string	Optional	The key of the display name of the user or system associated with a history record.
id	string	Optional	The ID of the user or system associated with a history record.
type	string	Optional	The type of the user or system associated with a history record.
url	string	Optional	The URL of the user or system associated with a history record.

Edit issue — request body — body transition fields value

Field	Type	Presence	Description and constraints
$	object	Root	The metadata describing an issue field. Additional keys: not allowed
allowedValues	array	Optional	The list of values allowed in the field. Read only: true
allowedValues[]	JSON	Each item	Read only: true
autoCompleteUrl	string	Optional	The URL that can be used to automatically complete the field. Read only: true
configuration	object	Optional	The configuration properties. Read only: true Additional keys: see wildcard field
configuration.*	JSON	Additional keys	Read only: true
defaultValue	JSON	Optional	The default value of the field. Read only: true
hasDefaultValue	boolean	Optional	Whether the field has a default value. Read only: true
key	string	Required within parent	The key of the field. Read only: true
name	string	Required within parent	The name of the field. Read only: true
operations	array	Required within parent	The list of operations that can be performed on the field. Read only: true
operations[]	string	Each item	Read only: true
required	boolean	Required within parent	Whether the field is required. Read only: true
schema	Model	Required within parent	Expand Edit issue — request body — body transition fields value schema The data type of the field. Read only: true

Referenced models: Edit issue — request body — body transition fields value schema

Policy, approvals and errors

SDK function policy ID: atlassian.dotransition. Catalog operation: dotransition. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["write:jira-work"]

No-content response statuses: [204]

Official provider source