Product events

Rate this page:

Jira events

Forge apps can subscribe to Jira events for:

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:

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

NameTypeDescription
eventTypestringThe event name avi:jira:created:issue.
issueIssueThe issue the event is related to.
atlassianIdstringThe ID of the user that has caused the event.
associatedUsersAssociatedUsers An object containing an array of one user, with the user being the one who created the issue.

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

NameTypeDescription
eventTypestringThe event name avi:jira:updated:issue.
issueIssueThe issue the event relates to.
atlassianIdstringThe ID of the user that has caused the event.
changelogChangelog A list of changes that have occurred in the update. The to and from fields display the accounts IDs of the assignees that the issue was to and from respectively, or null when the issue is unassigned or was previously unassigned.
associatedUsersAssociatedUsers An object containing an array of users, with the users being the one who made the update, and any assigned or unassigned users in the update being made.
associatedStatuses?AssociatedStatuses [Optional] If the issue status is updated, this contains an array of the current and previous statuses. Otherwise, this field is undefined. You can tell which is the current status by checking the changelog field.

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 a project'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 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

NameTypeDescription
eventTypestringThe event name avi:jira:assigned:issue.
issueIssueThe issue the event is related to.
atlassianIdstringThe ID of the user that has caused the event.
changelogChangelog A list of changes that have occurred in the update. The to and from fields display the accounts IDs of the assignees that the issue was to and from respectively, or null when the issue is unassigned or was previously unassigned.
associatedUsersAssociatedUsers An object containing an array of users, with the users being the one who made the update, and any users assigned or unassigned in the update being made.

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

NameTypeDescription
eventTypestringThe event name avi:jira:viewed:issue.
issueIssueThe issue the event is related to.
atlassianIdstringThe ID of the user that has caused the event.
userUserThe user who has viewed the issue.

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

NameTypeDescription
eventTypestringThe event name avi:jira:mentioned:issue.
issueIssueThe issue the event is related to.
atlassianIdstringThe ID of the user that has caused the event.
mentionedAccountIdsstring[]A list of account IDs of mentioned users.

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"
}

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.

We only support issue links within a single Jira instance.

This means that an event will not be triggered for links created between two Jira instances.

Payload

NameTypeDescription
eventTypestringThe event name, such as avi:jira:created:issuelink.
idstringID of the link.
sourceIssueIdstringID of the source issue.
destinationIssueIdstringID of the destination issue.
issueLinkTypeIssueLinkTypeAn object containing information about the link type.

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"
  }
}

Comment events

Forge apps can subscribe to these Jira comment events:

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

NameTypeDescription
eventTypestringThe event name avi:jira:commented:issue.
issueIssueThe issue the event is related to.
atlassianIdstringThe ID of the user that has caused the event.
associatedUsersAssociatedUsersThe user who has made the comment.
commentComment An object describing the comment, including its author, body content, and other metadata.

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;
}

interface User {
  accountId: 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"
            }
          ]
        }
      ]
    },
    "updateAuthor": {
      "accountId": "4ad9aa0c52dc1b420a791d12"
    },
    "created": "2021-01-20T16:43:44.320+1100",
    "updated": "2021-01-20T16:43:44.320+1100",
    "jsdPublic": true
  }
}

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.

NameTypeDescription
eventTypestringThe event name avi:jira:mentioned:comment.
issueIssueThe issue the event is related to.
atlassianIdstringThe ID of the user that has caused the event.
mentionedAccountIdsstring[]A list of the account IDs of the users mentioned in the comment.
commentComment An object describing the comment, including its author, body content, and other metadata.

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
  }
}

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

NameTypeDescription
eventTypestringThe event name such as avi:jira:created:field.
idstringID of the custom field.
keystringKey of the custom field.
typestringCustom field type.
typeNamestringCustom field type name.
namestringName of the custom field.
descriptionstringDescription of the custom field.

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

NameTypeDescription
eventTypestringThe event name such as avi:jira:created:field:context.
idstringID of the context.
fieldIdstringID of the custom field.
fieldKeystringKey of the custom field.
namestringName of the custom field context.
descriptionstringDescription of the custom field context.
projectIdslong[]List of project IDs associated with the context. If the list is empty, the context is global.
issueTypeIdsstring[]List of issue types IDs for the context. If the list is empty, the context refers to all issue types.

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

NameTypeDescription
eventTypestringThe event name avi:jira:updated:field:context:configuration.
customFieldIdstringID of the custom field.
customFieldKeystringKey of the custom field.
configurationIdlongID of the configuration.
fieldContextIdlongID of the context.
configurationstringStringified JSON of the updated configuration.

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
}

Jira expressions events

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.

The required OAuth scope is manage:jira-configuration.

Payload

NameTypeDescription
eventTypestringThe event name avi:jira:failed:expression.
timestampstringThe time when the expression failed to evaluate, in epoch milliseconds.
extensionIdstringThe ID of the extension where the expression is defined.
workflowIdstringThe ID of the workflow where the expression was evaluated.
workflowNamestringThe name of the workflow where the expression was evaluated.
conditionIdstring[Optional] The ID of the workflow condition where the expression is used.
validatorIdstring[Optional] The ID of the workflow validator where the expression is used.
expressionstringThe evaluated Jira expression.
errorMessagesstring[]The reasons why the expression failed to evaluate.
contextContextThe context of the expression's execution.

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"
      }
    }
  }
}

Rate this page: