Jira events

Forge apps can subscribe to Jira events for:

• Issues
• Issue links
• Issue worklogs
• Issue type
• Comments
• Custom fields
• Custom field context
• Custom field context configuration
• Workflows
• Project versions
• Projects
• Attachments
• Components
• Users
• Filters
• Time tracking provider

Your Forge app must have permission from the site admin to access the data it provides within the event payload. The OAuth scope required for each event is documented below.

Issue events

You can subscribe to these Jira issue events in Forge apps:

• Created: avi:jira:created:issue
• Updated: avi:jira:updated:issue
• Deleted: avi:jira:deleted:issue
• Assigned: avi:jira:assigned:issue
• Viewed: avi:jira:viewed:issue
• Mentioned on issue: avi:jira:mentioned:issue

Each event has a different payload format.

Issue created

An event with the name avi:jira:created:issue is sent when an issue is created.

The required OAuth scope is read:jira-work.

Payload

Type reference

1
2
interface Issue {
  id: string;
  key: string;
  fields: {
    summary?: string;
    issueType?: any;
    creator?: any;
    created?: string;
    project?: any;
    reporter?: User;
    assignee?: User | null;
    updated?: string;
    status?: any;
  };
}

interface AssociatedUsers {
  associatedUsers: User[];
}

interface User {
  accountId: string;
}

Example

This is an example of a payload for a newly created issue:.

1
2
{
  "eventType": "avi:jira:created:issue",
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/2/issuetype/10001",
        "id": "10001",
        "description": "Functionality or a feature expressed as a user goal.",
        "iconUrl": "https://example.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/2/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false,
        "avatarUrls": {
          "48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10419",
          "24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10419",
          "16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10419",
          "32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10419"
        }
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": null,
      "updated": "2021-01-20T15:58:12.797+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/2/status/10000",
        "description": "",
        "iconUrl": "https://example.atlassian.net/",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/2/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "associatedUsers": [
    {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    }
  ]
}

Issue updated

An event with the name avi:jira:updated:issue is sent when any field on an issue is modified. The level of detail in the event's changelog depends on which field is changed.

The required OAuth scope is read:jira-work.

Payload

Type reference

1
2
interface Issue {
  id: string;
  key: string;
  fields: {
    summary?: string;
    issueType?: any;
    creator?: any;
    created?: string;
    project?: any;
    reporter?: User;
    assignee?: User | null;
    updated?: string;
    status?: any;
  };
}

interface Changelog {
  items: Change[];
}

interface Change {
  field: string;
  fieldId: string;
  from: string | null;
  fromString: string | null;
  to: string | null;
  toString: string | null;
}

interface AssociatedUsers {
  associatedUsers: User[];
}

interface User {
  accountId: string;
}

Example

This is an example of updating an issue's description.

1
2
{
  "eventType": "avi:jira:updated:issue",
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/3/issuetype/10001",
        "id": "10001",
        "description": "Functionality or a feature expressed as a user goal.",
        "iconUrl": "https://example.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/3/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false,
        "avatarUrls": {
          "48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10419",
          "24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10419",
          "16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10419",
          "32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10419"
        }
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": null,
      "updated": "2021-01-20T16:13:59.255+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/3/status/10000",
        "description": "",
        "iconUrl": "https://example.atlassian.net/",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/3/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "changelog": {
    "id": "10154",
    "items": [
      {
        "field": "description",
        "fieldId": "description",
        "from": null,
        "fromString": null,
        "to": null,
        "toString": null
      }
    ]
  },
  "associatedUsers": [
    {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    }
  ]
}

Issue deleted

An event with the name avi:jira:deleted:issue is sent when an issue is deleted.

Keep in mind that cascading events aren’t emitted. For more information, see: Cascading events guide.

The required OAuth scope is read:jira-work.

Payload

Type reference

1
2
interface Issue {
  id: string;
  key: string;
  fields: {
    summary?: string;
    issueType?: any;
    creator?: any;
    created?: string;
    project?: any;
    reporter?: User;
    assignee?: User | null;
    updated?: string;
    status?: any;
  };
}

interface AssociatedUsers {
    associatedUsers: User[];
}

interface User {
  accountId: string;
}

Example

This is an example of deleting an issue.

1
2
{
  "eventType": "avi:jira:deleted:issue",
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/3/issuetype/10001",
        "id": "10001",
        "description": "Functionality or a feature expressed as a user goal.",
        "iconUrl": "https://example.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/3/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false,
        "avatarUrls": {
          "48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10419",
          "24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10419",
          "16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10419",
          "32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10419"
        }
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": null,
      "updated": "2021-01-20T16:13:59.255+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/3/status/10000",
        "description": "",
        "iconUrl": "https://example.atlassian.net/",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/3/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "associatedUsers": [
    {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    }
  ]
}

Issue assigned

An event with the name avi:jira:assigned:issue is sent when a user is assigned or unassigned from an issue. An "issue updated" event will also be sent when this occurs.

The required OAuth scope is read:jira-work.

Payload

Type reference

1
2
interface Issue {
  id: string;
  key: string;
  fields: {
    summary?: string;
    issueType?: any;
    creator?: any;
    created?: string;
    project?: any;
    reporter?: User;
    assignee?: User | null;
    updated?: string;
    status?: any;
  };
}

interface Changelog {
  items: Change[];
}

interface Change {
  field: string;
  fieldId: string;
  from: string | null;
  fromString: string | null;
  to: string | null;
  toString: string | null;
}

interface AssociatedUsers {
  associatedUsers: User[];
}

interface User {
  accountId: string;
}

Example

This is an example of assigning a user to a previously unassigned issue.

1
2
{
  "eventType": "avi:jira:assigned:issue",
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/3/issuetype/10001",
        "id": "10001",
        "description": "Functionality or a feature expressed as a user goal.",
        "iconUrl": "https://example.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/3/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false,
        "avatarUrls": {
          "48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10419",
          "24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10419",
          "16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10419",
          "32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10419"
        }
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": {
        "accountId": "123456:9af5200e-7667-459b-9c1f-38915c3644b9"
      },
      "updated": "2021-01-20T16:27:53.457+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/3/status/10000",
        "description": "",
        "iconUrl": "https://example.atlassian.net/",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/3/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "changelog": {
    "id": "10159",
    "items": [
      {
        "field": "assignee",
        "fieldtype": "jira",
        "fieldId": "assignee",
        "from": null,
        "fromString": null,
        "to": "123456:9af5200e-7667-459b-9c1f-38915c3644b9",
        "toString": null,
        "tmpFromAccountId": null,
        "tmpToAccountId": "123456:9af5200e-7667-459b-9c1f-38915c3644b9"
      }
    ]
  },
  "associatedUsers": [
    {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    },
    {
      "accountId": "123456:9af5200e-7667-459b-9c1f-38915c3644b9"
    }
  ]
}

Issue viewed

An event with the name avi:jira:viewed:issue is sent every time an issue is viewed by a user.

The required OAuth scope is read:jira-work.

Payload

Type reference

1
2
interface Issue {
  id: string;
  key: string;
  fields: {
    summary?: string;
    issueType?: any;
    creator?: any;
    created?: string;
    project?: any;
    reporter?: User;
    assignee?: User | null;
    updated?: string;
    status?: any;
  };
}

interface User {
  accountId: string;
}

Example

This is an example of an issue's creator viewing the issue.

1
2
{
  "eventType": "avi:jira:viewed:issue",
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/2/issuetype/10001",
        "id": "10001",
        "description": "Functionality or a feature expressed as a user goal.",
        "iconUrl": "https://example.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/2/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false,
        "avatarUrls": {
          "48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10419",
          "24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10419",
          "16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10419",
          "32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10419"
        }
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": null,
      "updated": "2021-01-20T15:58:12.797+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/2/status/10000",
        "description": "",
        "iconUrl": "https://example.atlassian.net/",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/2/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "user": {
    "accountId": "4ad9aa0c52dc1b420a791d12"
  }
}

Mentioned on issue

An event with the name avi:jira:mentioned:issue is sent every time an issue description is updated and users are mentioned. All users mentioned in the description are included in one event. A user mentioning themselves does not count as a mention.

The required OAuth scope is read:jira-work.

Payload

Type reference

1
2
interface Issue {
  id: string;
  key: string;
  fields: {
    summary?: string;
    issueType?: any;
    creator?: any;
    created?: string;
    project?: any;
    reporter?: User;
    assignee?: User | null;
    updated?: string;
    status?: any;
  };
}

interface User {
  accountId: string;
}

Example

This is an example of the issue's creator mentioning a different user in the issue's description.

1
2
{
  "eventType": "avi:jira:mentioned:issue",
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/3/issuetype/10001",
        "id": "10001",
        "description": "Functionality or a feature expressed as a user goal.",
        "iconUrl": "https://example.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/3/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false,
        "avatarUrls": {
          "48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10419",
          "24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10419",
          "16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10419",
          "32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10419"
        }
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": null,
      "updated": "2021-01-20T16:34:44.233+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/3/status/10000",
        "description": "",
        "iconUrl": "https://example.atlassian.net/",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/3/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "mentionedAccountIds": ["123456:9af5200e-7667-459b-9c1f-38915c3644b9"],
  "atlassianId": "4ad9aa0c52dc1b420a791d12"
}

Issue link events

You can subscribe to the following Jira issue link events in Forge apps:

• created: avi:jira:created:issuelink
• deleted: avi:jira:deleted:issuelink

The payload for all of these events is the same.

The required OAuth scope is read:jira-work.

Payload

Type reference

1
2
interface IssueLinkType {
  id: string;
  name: string;
  inward: string;
  outward: string;
}

Example

This is an example of the payload for when a Blocks issue link is created:

1
2
{
  "eventType": "avi:jira:created:issuelink",
  "id": "10000",
  "sourceIssueId": "10001",
  "destinationIssueId": "10002",
  "issueLinkType": {
    "id": "10000",
    "name": "Blocks",
    "inward": "is blocked by",
    "outward": "blocks"
  }
}

Issue worklog events

You can subscribe to these worklog events in Forge apps:

• Created: avi:jira:created:worklog
• Updated: avi:jira:updated:worklog
• Deleted: avi:jira:deleted:worklog

Keep in mind that for deletions, cascading events aren’t emitted. For more information, see: Cascading events guide.

OAuth 2.0 scopes required:

Classic: read:jira-work

Granular: read:comment:jira, read:group:jira, read:issue-worklog:jira, read:issue-worklog.property:jira, read:project-role:jira, read:user:jira, read:avatar:jira

Payload

Type reference

1
2
interface Worklog {
    id: string;
    issueId: string;
    author: User;
    updateAuthor: User;
    created: string;
    updated: string;
    started: string;
    timeSpent: string;
    timeSpentSeconds: number;
}

interface WorklogDeleted {
    id: string;
    issueId: string;
    author?: User;
    updateAuthor?: User;
    created: string;
    updated: string;
    started: string;
    timeSpent: string;
    timeSpentSeconds: number;
}

interface User {
    accountId: string;
}

Example

This is an example of the payload for worklog changes:

1
2
{
  "eventType": "avi:jira:created:worklog",
  "worklog": {
    "id": "10010",
    "issueId": "10000",
    "author": {
      "accountId": "70121:8a9e64b3-6662-0000-a57b-3cbc53fccf4d"
    },
    "updateAuthor": {
      "accountId": "70121:8a9e64b3-6662-0000-a57b-3cbc53fccf4d"
    },
    "created": "2023-03-01T17:00:00.000+0200",
    "updated": "2023-03-01T17:00:00.000+0200",
    "started": "2023-03-01T13:00:00.000+0200",
    "timeSpent": "4h",
    "timeSpentSeconds": 14400
  }
}

Issue type events

Your app must have permission from the site admin to access the data it provides within the event payload. The OAuth scopes required for each event are documented below. You can subscribe to the following issue type events in Forge apps:

• Issue type created: avi:jira:created:issuetype
• Issue type updated: avi:jira:updated:issuetype
• Issue type deleted: avi:jira:deleted:issuetype

OAuth 2.0 scopes required:

Classic: manage:jira-configuration

Granular: read:issue-type:jira

All events have the same payload format.

Payload

Type reference

1
2
interface IssueType {
    id: string;
    name: string;
    description: string;
    scope: Scope;
}

interface Scope {
    type: 'GLOBAL' | 'PROJECT';
    projectId?: string;  // present when type is PROJECT
}

Example

This is an example of a payload for a newly created issueType:

1
2
{
  "eventType": "avi:jira:created:issuetype",
  "issueType": {
    "id": "10000",
    "name": "IssueType 1",
    "description": "This is a Jira issueType",
    "scope": {
      "type": "GLOBAL"
    }
  },
  "atlassianId": "60da07f475365000708f0119"
}

This is an example of a payload for updating the name of an issueType:

1
2
{
  "eventType": "avi:jira:updated:issuetype",
  "issueType": {
    "id": "10000",
    "name": "IssueType 1 updated",
    "description": "This is a Jira issueType",
    "scope": {
      "type": "GLOBAL"
    }
  },
  "atlassianId": "60da07f475365000708f0119"
}

Comment events

Forge apps can subscribe to these Jira comment events:

• Comment on issue: avi:jira:commented:issue
• Mentioned in comment: avi:jira:mentioned:comment
• Comment deleted: avi:jira:deleted:comment

Comment on issue

An event with the name avi:jira:commented:issue is sent each time a comment is created or edited.

The required OAuth scope is read:jira-work.

Payload

Type reference

1
2
interface Issue {
  id: string;
  key: string;
  fields: {
    summary?: string;
    issueType?: any;
    creator?: any;
    created?: string;
    project?: any;
    reporter?: User;
    assignee?: User | null;
    updated?: string;
    status?: any;
  };
}

interface AssociatedUsers {
  associatedUsers: User[];
}

interface Comment {
  id: string;
  author?: User;
  body: any;
  updateAuthor?: User;
  created: string;
  updated: string;
  jsdPublic: boolean;
  visibility?: Visibility;
}

interface User {
  accountId: string;
}

interface Visibility {
    type: string,
    value: string,
    identifier: string
}

Example

This is an example of the issue's creator adding a comment to the issue.

1
2
{
  "eventType": "avi:jira:commented:issue",
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/3/issuetype/10001",
        "id": "10001",
        "description": "Functionality or a feature expressed as a user goal.",
        "iconUrl": "https://example.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/3/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false,
        "avatarUrls": {
          "48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10419",
          "24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10419",
          "16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10419",
          "32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10419"
        }
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": null,
      "updated": "2021-01-20T16:43:22.076+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/3/status/10000",
        "description": "",
        "iconUrl": "https://example.atlassian.net/",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/3/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "associatedUsers": [
    {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    }
  ],
  "comment": {
    "id": "10038",
    "author": {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    },
    "body": {
      "version": 1,
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "This is a very normal comment"
            }
          ]
        },
        {
          "type": "mediaSingle",
          "content": [
            {
              "type": "media",
              "attrs": {
                "type": "file",
                "id": "d7357622-de83-40c1-a40f-0365c0f6589f",
                "collection": "",
                "width": 620,
                "height": 465
              }
            }
          ],
          "attrs": {
            "layout": "align-start"
          }
        }        
      ]
    },
    "updateAuthor": {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    },
    "created": "2021-01-20T16:43:44.320+1100",
    "updated": "2021-01-20T16:43:44.320+1100",
    "jsdPublic": true,
    "visibility": {
      "type": "group",
      "value": "site-admins",
      "identifier": "b9c0b7da-5fe9-42dc-90a6-2c46faddb518"
    }
  }
}

Mentioned in comment

An event with the name avi:jira:mentioned:comment is sent each time users are mentioned when a comment is created or edited. All users mentioned in the comment are included in one event.

The required OAuth scope is read:jira-work.

Type reference

1
2
interface Issue {
  id: string;
  key: string;
  fields: {
    summary?: string;
    issueType?: any;
    creator?: any;
    created?: string;
    project?: any;
    reporter?: User;
    assignee?: User | null;
    updated?: string;
    status?: any;
  };
}

interface Comment {
  id: string;
  author?: User;
  body: any;
  updateAuthor?: User;
  created: string;
  updated: string;
  jsdPublic: boolean;
}

interface User {
  accountId: string;
}

Example

This is an example of the issue's creator mentioning a different user in a comment.

1
2
{
  "eventType": "avi:jira:mentioned:comment",
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/3/issuetype/10001",
        "id": "10001",
        "description": "Functionality or a feature expressed as a user goal.",
        "iconUrl": "https://example.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/3/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false,
        "avatarUrls": {
          "48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10419",
          "24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10419",
          "16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10419",
          "32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10419"
        }
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": null,
      "updated": "2021-01-20T16:43:44.320+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/3/status/10000",
        "description": "",
        "iconUrl": "https://example.atlassian.net/",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/3/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "mentionedAccountIds": [
    "123456:9af5200e-7667-459b-9c1f-38915c3644b9"
  ],
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "comment": {
    "id": "10039",
    "author": {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    },
    "body": {
      "version": 1,
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "This is a comment and I am going to mention "
            },
            {
              "type": "mention",
              "attrs": {
                "id": "123456:9af5200e-7667-459b-9c1f-38915c3644b9",
                "text": "Firstname Lastname"
              }
            },
            {
              "type": "text",
              "text": " in it"
            }
          ]
        }
      ]
    },
    "updateAuthor": {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    },
    "created": "2021-01-20T16:44:23.078+1100",
    "updated": "2021-01-20T16:44:23.078+1100",
    "jsdPublic": true
  }
}

Comment deleted

An event with the name avi:jira:deleted:comment is sent each time a comment is deleted.

Keep in mind that cascading events aren’t emitted. For more information, see: Cascading events guide.

The required OAuth scope is read:jira-work.

Payload

Type reference

1
2
interface Issue {
  id: string;
  key: string;
  fields: {
    summary?: string;
    issueType?: any;
    creator?: any;
    created?: string;
    project?: any;
    reporter?: User;
    assignee?: User | null;
    updated?: string;
    status?: any;
  };
}

interface Comment {
  id: string;
  author?: User;
  body: any;
  updateAuthor?: User;
  created: string;
  updated: string;
  jsdPublic: boolean;
  visibility?: Visibility;
}

interface User {
  accountId: string;
}

interface Visibility {
    type: string,
    value: string,
    identifier: string
}

Example

This is an example of a user deleting a comment they wrote on an issue.

1
2
{
  "eventType": "avi:jira:deleted:comment",
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/3/issuetype/10001",
        "id": "10001",
        "description": "Functionality or a feature expressed as a user goal.",
        "iconUrl": "https://example.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/3/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false,
        "avatarUrls": {
          "48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10419",
          "24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10419",
          "16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10419",
          "32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10419"
        }
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": null,
      "updated": "2021-01-20T16:43:22.076+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/3/status/10000",
        "description": "",
        "iconUrl": "https://example.atlassian.net/",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/3/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "comment": {
    "id": "10038",
    "author": {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    },
    "body": {
      "version": 1,
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "This is a very normal comment"
            }
          ]
        },
        {
          "type": "mediaSingle",
          "content": [
            {
              "type": "media",
              "attrs": {
                "type": "file",
                "id": "d7357622-de83-40c1-a40f-0365c0f6589f",
                "collection": "",
                "width": 620,
                "height": 465
              }
            }
          ],
          "attrs": {
            "layout": "align-start"
          }
        }        
      ]
    },
    "updateAuthor": {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    },
    "created": "2021-01-20T16:43:44.320+1100",
    "updated": "2021-01-20T16:43:44.320+1100",
    "jsdPublic": true,
    "visibility": {
      "type": "group",
      "value": "site-admins",
      "identifier": "b9c0b7da-5fe9-42dc-90a6-2c46faddb518"
    }
  }
}

Custom field events

You can subscribe to these Jira custom field events in Forge apps:

• Created: avi:jira:created:field
• Updated: avi:jira:updated:field
• Trashed: avi:jira:trashed:field
• Restored: avi:jira:restored:field
• Deleted: avi:jira:deleted:field

The payload for all of these events is the same.

The required OAuth scope is manage:jira-configuration.

Payload

Example

This is an example of the payload for a new floating-point number field:

1
2
{
  "eventType": "avi:jira:created:field",
  "id": "customfield_10000",
  "key": "customfield_10000",
  "type": "com.atlassian.jira.plugin.system.customfieldtypes:float",
  "typeName": "Number Field",
  "name": "custom-number-field",
  "description": "Float value"
}

This is an example of the payload for a new Forge custom field (note that the key format is different):

1
2
{
  "id": "customfield_10001",
  "key": "forge-custom-field-type__df712142-1fd0-4ca9-8822-91e931c44ad8",
  "type": "com.atlassian.forge:ari:cloud:ecosystem::extension/8e921916-9c66-4611-ad0b-5a9a47324a12/0f483ab5-ba3a-4961-9dda-37e106c227af/static/forge-custom-field-type",
  "typeName": "forge-custom-field-type",
  "name": "forge-custom-field",
  "description": "Forge custom field"
}

Custom field context events

You can subscribe to these Jira custom field context events in Forge apps:

• Created: avi:jira:created:field:context
• Updated: avi:jira:updated:field:context
• Deleted: avi:jira:deleted:field:context

The payload for all of these events is the same.

The required OAuth scope is manage:jira-configuration.

Payload

Example

This is an example of the payload for a new default custom field context:

1
2
{
  "eventType": "avi:jira:created:field:context",
  "id": "10169",
  "fieldId": "customfield_10061",
  "fieldKey": "customfield_10061",
  "name": "Default configuration scheme for new custom field",
  "description": "Default configuration scheme generated by Jira",
  "projectIds": [],
  "issueTypeIds": []
}

This is an example of the payload for a new Forge custom field context (note that the key format is different):

1
2
{
  "id": "10169",
  "fieldId": "customfield_10061",
  "fieldKey": "forge-custom-field-type__df712142-1fd0-4ca9-8822-91e931c44ad8",
  "name": "Bug fields context",
  "description": "A context used to define the custom field options for bugs.",
  "projectIds": [
    10002,
    10003
  ],
  "issueTypeIds": [
    "10012",
    "10009"
  ]
}

Custom field context configuration events

An event with the name avi:jira:updated:field:context:configuration is sent each time the custom field context configuration is updated.

You can subscribe to this event in Forge apps.

The required OAuth scope is manage:jira-configuration.

Payload

Example

This is an example of a custom field context with the configuration set to an object:

1
2
{
  "eventType": "avi:jira:updated:field:context:configuration",
  "customFieldId": "customfield_10039",
  "customFieldKey": "forge-custom-field__df712142-1fd0-4ca9-8822-91e931c44ad8",
  "configurationId": 10139,
  "fieldContextId": 10139,
  "configuration": "{\"value1\": 5, \"value2\": 1}"
}

This is an example of a custom field context with the configuration set to null:

1
2
{
  "customFieldId": "customfield_10039",
  "customFieldKey": "forge-custom-field__df712142-1fd0-4ca9-8822-91e931c44ad8",
  "configurationId": 10139,
  "fieldContextId": 10139
}

Workflow events

You can subscribe to these Jira workflow events in Forge apps:

• Expression evaluation failed: avi:jira:failed:expression

Other Jira product events can also be sent after transitioning an issue, depending on what has changed during the transition:

• Issue created: avi:jira:created:issue for the initial transition
• Issue updated: avi:jira:updated:issue for other transitions
• Issue deleted: avi:jira:deleted:issue when issue has been deleted
• Issue assigned: avi:jira:assigned:issue if the issue is assigned while making a transition
• Mentioned on issue: avi:jira:mentioned:issue when a user is mentioned on an issue while making a transition
• Comment on issue: avi:jira:commented:issue if a comment is added while making a transition

Expression evaluation failed

Whenever an app-registered Forge workflow condition or Forge workflow validator based on a Jira expression fails while executing, an avi:jira:failed:expression event is sent.

You can subscribe to this event in Forge apps. This event will only reach the app that registered the failing expression.

OAuth 2.0 scopes required:

Classic: manage:jira-configuration

Granular: read:workflow:jira, read:issue:jira, read:project:jira

Payload

Type reference

1
2
interface Context {
  issue: IdKey;
  project: IdKey;
  user: User;
  transition: Transition;
}

interface IdKey {
  id: string;
  key: string;
}

interface User {
  accountId: string;
}

interface Transition {
  id: string;
  name: string;
  from: StatusId;
  to: StatusId;
}

interface StatusId {
  id: string;
}

Example

This is an example of Jira expression evaluation failure when used in a Forge workflow condition:

1
2
{
  "eventType": "avi:jira:failed:expression",
  "timestamp": "1651155160997",
  "extensionId": "ari:cloud:ecosystem::extension/appId/envId/static/forge-condition",
  "workflowId": "0283338c-0de0-4920-823b-286af0a36965",
  "workflowName": "Test Workflow",
  "conditionId": "c23ff04e-9fd2-4a6f-be37-ade253d1cdc9",
  "expression": "issue.assignee.unknown",
  "errorMessages": [
    "Evaluation failed: \"issue.assignee.unknown\" - Unrecognized property of `issue.assignee`: \"unknown\" ('unknown'). Available properties of type 'User' are: 'accountId', 'displayName', 'getProjectRoles', 'groupIds', 'groups', 'permissions', 'properties'"
  ],
  "context": {
    "issue": {
      "id": "10000",
      "key": "TEST-1"
    },
    "project": {
      "id": "10000",
      "key": "TEST"
    },
    "user": {
      "accountId": "00000-0000-0000-00000"
    },
    "transition": {
      "id": "11",
      "name": "In progress",
      "from": {
        "id": "1"
      },
      "to": {
        "id": "2"
      }
    }
  }
}

Run post function event

A post function event is sent each time the transition with configured Forge workflow post function is performed. It is used to invoke the Forge function defined in the jira:workflowPostFunction module.

OAuth 2.0 scopes required:

Classic: read:jira-work, manage:jira-configuration

Granular: read:issue-meta:jira, read:issue-security-level:jira, read:issue.vote:jira, read:issue.changelog:jira, read:avatar:jira, read:issue:jira, read:status:jira, read:user:jira, read:field-configuration:jira, read:issue.transition:jira, read:comment:jira, read:comment.property:jira, read:group:jira, read:project:jira, read:project-role:jira, read:screen:jira, read:workflow:jira, read:webhook:jira, read:project-category:jira

Payload

Type reference

1
2
interface Issue {
    id: string;
    key: string;
    fields: {
        summary: string;
        issuetype: IssueType;
        creator: User;
        created: string;
        project: Project;
        reporter: User;
        assignee: User | null;
        updated: string;
        status: Status;
    };
}

interface IssueType {
    self: string;
    id: string;
    name: string;
    subtask: boolean;
    avatarId: number;
    hierarchyLevel: number;
}

interface User {
    accountId: string;
}

interface Project {
    self: string;
    id: string;
    key: string;
    name: string;
    projectTypeKey: string;
    simplified: boolean;
}

interface Status {
    self: string;
    name: string;
    id: string;
    statusCategory: StatusCategory;
}

interface StatusCategory {
    self: string;
    id: string;
    key: string;
    colorName: string
    name: string
}

interface Transition {
    id: string;
    name: string;
    from: StatusId;
    to: StatusId;
    executionId: string;
}

interface StatusId {
    id: string;
}

interface Workflow {
    id: string;
    name: string;
}

interface Changelog {
    id: string
    items: Change[];
}

interface Change {
    field: string;
    fieldId: string;
    fieldtype: string
}

interface Comment {
    id: string;
}

interface Context {
  cloudId: string;
  moduleKey: string
}

interface RetryOptions {
  retryData: any;
  retryCount: number;
  retryReason: InvocationErrorCode
}

Example

1
2
{
  "issue": {
    "id": "10073",
    "key": "SP-10",
    "fields": {
      "summary": "A descriptive title",
      "issuetype": {
        "self": "https://example.atlassian.net/rest/api/2/issuetype/10001",
        "id": "10001",
        "name": "Story",
        "subtask": false,
        "avatarId": 10315,
        "hierarchyLevel": 0
      },
      "creator": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "created": "2021-01-20T15:58:12.797+1100",
      "project": {
        "self": "https://example.atlassian.net/rest/api/2/project/10000",
        "id": "10000",
        "key": "SP",
        "name": "Sample Project",
        "projectTypeKey": "software",
        "simplified": false
      },
      "reporter": {
        "accountId": "4ad9aa0c52dc1b420a791d12"
      },
      "assignee": null,
      "updated": "2021-01-20T15:58:12.797+1100",
      "status": {
        "self": "https://example.atlassian.net/rest/api/2/status/10000",
        "name": "Backlog",
        "id": "10000",
        "statusCategory": {
          "self": "https://example.atlassian.net/rest/api/2/statuscategory/2",
          "id": 2,
          "key": "new",
          "colorName": "blue-gray",
          "name": "To Do"
        }
      }
    }
  },
  "transition": {
    "id": "11",
    "name": "In progress",
    "from": {
      "id": "1"
    },
    "to": {
      "id": "2"
    },
    "executionId": "6540951a-7c88-4620-835b-61aab8bbb13e"
  },
  "workflow": {
    "id": "b02bda32-5d09-4cbd-bab1-d0114fe7cf1c",
    "name": "Software Simplified Workflow"
  },
  "atlassianId": "60da07f475365000708f0119",
  "changelog": {
    "id": "10050",
    "items": [
      {
        "field": "status",
        "fieldtype": "jira",
        "fieldId": "status"
      }
    ]
  },
  "comment": {
    "id": "10076"
  },
  "configuration": {
    "key1": "value",
    "key2": "value2"
  },
  "context": {
    "cloudId": "my-cloud-id",
    "moduleKey": "my-forge-module"
  },
  "retryContext": {
    "retryData": null,
    "retryCount": 3,
    "retryReason": "TUNNEL_PLATFORM_ERROR"
  }
}

Project version events

You can subscribe to these project version events in Forge apps:

• Created: avi:jira:created:version

• Updated: avi:jira:updated:version

• Deleted: avi:jira:deleted:version

• Released: avi:jira:released:version

• Unreleased: avi:jira:unreleased:version

• Archived: avi:jira:archived:version

• Unarchived: avi:jira:unarchived:version

• Moved: avi:jira:moved:version

• Merged: avi:jira:merged:version

OAuth 2.0 scopes required:

Classic: read:jira-work

Granular: read:project-version:jira

Payload

Example

These are examples of the payloads for version changes:

1
2
{
  "eventType": "avi:jira:created:version",
  "version": {
    "id": "10000",
    "projectId": "10000",
    "name": "Version 1.0a",
    "sequence": "1",
    "archived": false,
    "released": false,
    "overdue": true
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12"
}

1
2
{
  "eventType": "avi:jira:merged:version",
  "version": {
    "id": "10001",
    "projectId": "10000",
    "name": "Version 19c",
    "sequence": "2",
    "startDate": "2019-11-17",
    "releaseDate": "2020-03-11",
    "archived": false,
    "released": true,
    "overdue": false
  },
  "mergedVersion": {
    "id": "10000",
    "projectId": "10000",
    "name": "Version 1.0b",
    "sequence": "1",
    "archived": false,
    "released": false,
    "overdue": true
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12"
}

Project version deleted

Payload

Example

This is an example payload for a project version deleted event:

1
2
{
  "eventType": "avi:jira:deleted:version",
  "version": {
    "id": "10067",
    "projectId": "10003",
    "name": "Version 1.0b",
    "sequence": "34",
    "archived": false,
    "released": false,
    "overdue": false
  },
  "newFixVersion": {
    "id": "10015",
    "projectId": "10003",
    "name": "Version 1.0c",
    "sequence": "4",
    "releaseDate": "2010-07-06",
    "archived": false,
    "released": true,
    "overdue": false
  },
  "newAffectsVersion": {
    "id": "10021",
    "projectId": "10003",
    "name": "Version 1.0d",
    "sequence": "8",
    "releaseDate": "2010-07-06",
    "archived": false,
    "released": true,
    "overdue": false
  },
  "customFieldReplacements": [
    {
      "fieldId": "10037",
      "newVersionId": "10055"
    }
  ],
  "atlassianId": "4ad9aa0c52dc1b420a791d12"
}

Type reference

1
2
interface Version {
    id: string;
    projectId: string;
    name: string;
    description?: string; // limited to 16384 characters
    sequence: string;
    startDate?: string;
    releaseDate?: string;
    released: boolean;
    archived: boolean;
    overdue: boolean;
}

interface CustomFieldReplacement {
    fieldId: string;
    newVersionId: string;
}

Project events

You can subscribe to the following Jira project events in Forge apps:

• Project created: avi:jira:created:project
• Project updated: avi:jira:updated:project
• Project moved to trash: avi:jira:softdeleted:project
• Project deleted permanently: avi:jira:deleted:project
• Project archived: avi:jira:archived:project
• Project unarchived: avi:jira:unarchived:project
• Project restored: avi:jira:restored:project

OAuth 2.0 scopes required:

Classic: read:jira-work

Granular: read:project:jira

All events have the same payload format.

Payload

Type reference

1
2
interface Project {
    id: string;
    key: string;
    scopeType: string; 'GLOBAL | PROJECT'
    product: string;
    projectTemplateKey?:string; // only present in avi:jira:created:project
}

Examples

This is an example of a payload for a newly created project with projectTemplateKey:

1
2
{
  "eventType": "avi:jira:created:project",
  "project": {
    "id": "10003",
    "key": "EX",
    "scopeType": "GLOBAL",
    "product": "software",
    "projectTemplateKey": "com.atlassian.jira-core-project-templates:jira-core-simplified-process-control"
  }
}

This is an example of a payload for an updated project:

1
2
{
  "eventType": "avi:jira:updated:project",
  "project": {
    "id": "10003",
    "key": "EX",
    "scopeType": "GLOBAL",
    "product": "software"
  }
}

This is an example of a payload for a deleted project:

1
2
{
  "eventType": "avi:jira:deleted:project",
  "project": {
    "id": "10003",
    "key": "EX",
    "scopeType": "GLOBAL",
    "product": "software"
  }
}

Attachment events

You can subscribe to this Jira attachment event in Forge apps:

• Attachment created: avi:jira:created:attachment
• Attachment deleted: avi:jira:deleted:attachment

Keep in mind that for deletions, cascading events aren’t emitted. For more information, see: Cascading events guide.

OAuth 2.0 scopes required:

Classic: read:jira-work

Granular: read:attachment:jira

Payload

Type reference

1
2
interface Attachment {
    id: string;
    issueId: string;
    fileName: string;
    createDate: string;
    size: string;
    mimeType: string;
    author?: User;
}

interface User {
    accountId: string;
}

Example

This is an example of a newly created attachment event:

1
2
{
  "eventType": "avi:jira:created:attachment",
  "attachment": {
    "id": "10",
    "issueId": "10001",
    "fileName": "fileName.png",
    "createDate": "2023-08-04 07:53:12.189",
    "size": "10587",
    "mimeType": "image/png",
    "author": {
      "accountId": "70121:8a9e64b3-6662-4485-a57b-3cbc53fccf4d"
    }
  }
}

This is an example of an attachment deleted event:

1
2
{
  "eventType": "avi:jira:deleted:attachment",
  "attachment": {
    "id": "10",
    "issueId": "10001",
    "fileName": "fileName.png",
    "createDate": "2023-08-04 07:53:12.189",
    "size": "10587",
    "mimeType": "image/png",
    "author": {
      "accountId": "70121:8a9e64b3-6662-4485-a57b-3cbc53fccf4d"
    }
  }
}

Component events

You can subscribe to these component events in Forge apps:

• Component created: avi:jira:created:component
• Component updated: avi:jira:updated:component
• Component deleted: avi:jira:deleted:component

Keep in mind that cascading events for deleted components aren’t emitted. For more information, see: Cascading events guide.

OAuth 2.0 scopes required:

Classic: read:jira-work

Granular (Component created/updated): read:project:jira, read:user:jira
Granular (Component deleted): read:project:jira, read:user:jira, read:project.component:jira

All events have the same payload format.

Payload

Type reference

1
2
interface Component {
    id: string;
    name: string;           // limited to 256 characters, dropped when the limit is exceeded
    description: string;    // limited to 256 characters, dropped when the limit is exceeded
    assigneeType: string;
    lead: User;
    realAssignee: User;
    isAssigneeTypeValid: boolean;
    project: string;
    projectId: string
}

interface User {
    accountId: string;
}

Example

This is an example of a payload for a newly created component:

1
2
{
  "eventType": "avi:jira:created:component",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "component": {
    "id": "10000",
    "name": "Component 1",
    "description": "This is a Jira component",
    "assigneeType": "PROJECT_LEAD",
    "lead": {
      "accountId": "70121:8a9e64b3-6662-4485-a57b-3cbc53fccf4d"
    },
    "realAssignee": {
      "accountId": "70121:8a9e64b3-6662-4485-a57b-3cbc53fccf4d"
    },
    "isAssigneeTypeValid": true,
    "project": "RB",
    "projectId": 10010
  }
}

This is an example of a payload for an updated name of component:

1
2
{
  "eventType": "avi:jira:updated:component",
  "atlassianId": "4ad9aa0c52dc1b420a791d12",
  "component": {
    "id": "10000",
    "name": "Component 1 updated",
    "description": "This is a Jira component",
    "assigneeType": "PROJECT_LEAD",
    "lead": {
      "accountId": "70121:8a9e64b3-6662-4485-a57b-3cbc53fccf4d"
    },
    "realAssignee": {
      "accountId": "70121:8a9e64b3-6662-4485-a57b-3cbc53fccf4d"
    },
    "isAssigneeTypeValid": true,
    "project": "RB",
    "projectId": 10010
  }
}

User events

You can subscribe to these user events in Forge apps:

• User created: avi:jira:created:user
• User updated: avi:jira:updated:user
• User deleted: avi:jira:deleted:user

OAuth 2.0 scopes required:

Classic: read:jira-user

Granular: read:application-role:jira, read:group:jira, read:user:jira, read:avatar:jira

User created/updated

User created and updated events have the same payload format.

Payload

Type reference

1
2
interface UserDetails {
  accountId: string;
  avatarUrls: any;
  displayName: string;
  emailAddress?: string; // Depending on the user’s privacy setting, this may not be present.
  active: boolean;
  timeZone?: string; // Depending on the user’s privacy setting, this may not be present.
  accountType:
      'atlassian' // Regular Atlassian user account.
    | 'app'       // System account used by Connect applications and OAuth to represent external systems.
    | 'customer'  // Used by Jira Service Desk for external service desks.
    | 'unknown';
}

Example

This is an example of a payload for a user updated event:

1
2
{
  "eventType": "avi:jira:updated:user",
  "user": {
    "accountId": "l345klhgk456gkg45lkg45lj",
    "avatarUrls": {
      "48x48": "https://example.atlassian.net/secure/useravatar?avatarId=10419",
      "24x24": "https://example.atlassian.net/secure/useravatar?size=small&s=small&avatarId=10419",
      "16x16": "https://example.atlassian.net/secure/useravatar?size=xsmall&s=xsmall&avatarId=10419",
      "32x32": "https://example.atlassian.net/secure/useravatar?size=medium&s=medium&avatarId=10419"
    },
    "displayName": "Charlie Atlas",
    "emailAddress": "charlie@atlassian.com",
    "active": true,
    "timeZone": "Australia/Sydney",
    "accountType": "atlassian"
  }
}

User deleted

User deleted event has the following payload format.

Payload

Type reference

1
2
interface User {
  accountId: string;
}

Example

This is an example of a payload for a user deleted event:

1
2
{
  "eventType": "avi:jira:deleted:user",
  "user": {
    "accountId": "l345klhgk456gkg45lkg45lj"
  }
}

Filter events

You can subscribe to these filter events in Forge apps:

• Filter created: avi:jira:created:filter
• Filter updated: avi:jira:updated:filter
• Filter deleted: avi:jira:deleted:filter

The payload for all of these events is the same.

OAuth 2.0 scopes required:

Classic: manage:jira-configuration

Granular: read:filter:jira, read:jql:jira

Payload

Type reference

1
2
interface Filter {
  id: string;
  name: string;
  description?: string; // limited to 10K characters, dropped when the limit is exceeded
  jql: string; // limited to 90K characters, dropped when the limit is exceeded
  owner: User;
}

interface User {
    accountId: string;
}

Example

This is an example of a payload for a user updated event:

1
2
{
  "eventType": "avi:jira:updated:filter",
  "filter": {
    "id": "10006",
    "name": "Important issues",
    "description": "Some description",
    "jql": "labels in (important, very-important)",
    "owner": {
      "accountId": "456xyz0c52dc1b420a791ta4"
    }
  },
  "atlassianId": "4ad9aa0c52dc1b420a791d12"
}

Time tracking provider events

An event with the name avi:jira:timetracking:provider:changed is sent each time the time tracking provider is changed.

You can subscribe to this event in Forge apps.

The required OAuth scope is manage:jira-configuration.

Payload

Type reference

1
2
interface Property {
    key: string;
    value: string;
}

Example

This is an example of a time tracking provider changed event with the provider set to a Forge app provider:

1
2
{
  "eventType": "avi:jira:timetracking:provider:changed",
  "property": {
    "key": "jira.timetracking.selected",
    "value": "ari:cloud:ecosystem::extension/e62f20a2-4b61-4dbe-bfb9-9a88b5e3ac84/548c5df1-24aa-4f7c-bbbb-3038d947cb05/static/timetracking-provider"
  }
}

This is an example of a time tracking provider changed event with the provider set to a Connect app provider:

1
2
{
  "eventType": "avi:jira:timetracking:provider:changed",
  "property": {
    "key": "jira.timetracking.selected",
    "value": "com.example.timetracking-plugin__timetracking-provider"
  }
}