Skip to main content
@frogbotai/piece-jira works with Jira Cloud through its REST API. Agents create, update, transition and comment on issues; imports page through projects, issues, sprints, history and attachments; polling triggers react to new and changed issues.

Connect Jira

Each piece instance works with one Jira Cloud site, set by siteUrl. People connect with a pasted Atlassian API token, with Sign in with Atlassian, or either:
Drop oauth and oauth: true to offer tokens only. Atlassian recommends sign-in over pasted tokens, since a token acts with all of its owner’s access. See factory options for the shared options. Jira Cloud only: Jira Server and Data Center aren’t supported.

Make an API token

  1. Sign in to Atlassian as the account FrogBot should act as, and open API tokens.
  2. Choose Create API token, name it, and copy it.
  3. Connect with that account’s email as email and the token as apiToken.

Register an Atlassian OAuth app

  1. In the Atlassian developer console, choose Create → OAuth 2.0 integration.
  2. Under Authorization, add OAuth 2.0 (3LO) with the instance’s callback URL: https://your-app.example.com/api/connections/jira/callback (use your instance slug).
  3. Under Permissions → Jira API, add the classic scopes read:jira-work, write:jira-work and read:jira-user. For boards and sprints, also add the granular scopes read:board-scope:jira-software, read:sprint:jira-software and read:project:jira.
  4. Under Settings, copy the client ID and secret into oauth.
  5. To let people outside your own Atlassian account sign in, set Distribution to sharing.
A sign-in can reach several sites. FrogBot looks the account’s sites up once per connection and uses the one matching siteUrl, or the only one. With several sites and no siteUrl, or no match, the call fails and lists the sites the account can reach.

Actions

Issue actions take an issue key such as OPS-12, or its numeric id.

Write formatted text

Jira stores rich text, such as descriptions and comments, in its own JSON format, ADF. Every rich-text input takes markdown, and FrogBot converts it:
Paragraphs, headings, bold, italic, strikethrough, inline code, code blocks, links, bullet and numbered lists, quotes and horizontal rules convert. Anything else, such as tables and images, stays as plain text. An ADF document, as an object or a JSON string, is sent unchanged. Reads return Jira’s ADF.

Page through a site

These actions return one page at a time, for imports:
Each takes limit (1–100, default 50) and cursor, the previous page’s pagination.nextCursor, which is null on the last page. Keep the other inputs the same between pages. Epics are issues whose children point to them through parent, so searchIssues reads them. Jira errors keep Jira’s messages and status. When Jira rate-limits a request, which a large import can, FrogBot waits for its Retry-After and retries up to 3 times, stopping early if the request is aborted.

Triggers

The issue and comment triggers take an optional jql filter, such as project = OPS. All nine are polling triggers that check every 5 minutes. The first poll only records where to start, so nothing already in Jira is emitted. Issue polls look 15 minutes past the previous one, since Jira’s search can lag, and skip what they already emitted. A poll has no signed-in person, so mount it on a separate instance with its own factory auth; the instance in your connection entry throws missing without a signed-in person. Give the instance an API token, ideally for a dedicated Jira account:
Triggers see what that account can see. assignedToMe watches assignments to it.