Skip to main content
A company connects one Jira Cloud site by OAuth. Olyros registers a webhook on the projects the company chooses, offers every issue event to the company’s workflows, and lets workflows and schedules create, comment on, label and transition issues. The connection lives under Settings -> Integrations (/integrations), then the Jira connection (/integrations/jira/:connectionId with Status (status), Projects (projects), Webhooks (webhooks) and Settings (settings) tabs). Jira has no GraphQL surface; everything is REST under /api/jira.

​
What it does

  • Connect by OAuth 2.0 (3LO). GET /api/jira/connect stages a single-use state (10 minutes) and starts Atlassian consent; GET /api/jira/callback redeems it, re-checks that the initiator is still a member, exchanges the code, picks the accessible site and stores a JiraConnection (cloud id, site URL and name, scopes, encrypted access and refresh tokens). Access tokens are refreshed proactively five minutes before expiry. Status is active, token_expired, error or disconnected; one connection per site per company (uq_jira_conn_company_cloud).
  • Register the webhook. POST /api/jira/connections/{connection_id}/webhooks registers a dynamic webhook for jira:issue_created, jira:issue_updated and jira:issue_deleted scoped by monitored_projects, with a per-connection callback token in the URL. Atlassian webhooks expire after 30 days; Olyros refreshes them (refresh_webhook) and can purge stale registrations.
  • Receive events safely. POST /api/jira/webhooks/{token}: the token hash selects the connection and its company (only active connections; an unknown or inactive token gets a plain 404); each connection is held to 120 requests per rolling minute (429 beyond); the body is capped at the platform’s maximum payload size; when the platform’s Jira app secret is configured the x-hub-signature is verified; the body is deduplicated for seven days (JiraWebhookDelivery: claimed, processed, failed); events for projects outside monitored_projects are dropped. Deliveries are listed at GET .../webhook-events. Only the per-connection URL with its token accepts deliveries; a webhook registered on a connection before the token was introduced must be registered again.
  • Start workflows. Each accepted event is offered to active workflows whose jira_event trigger names this connection with the matching event type (status_change, issue_created, label_added on added labels only, or issue_deleted); jira_filter nodes then narrow on status_to, labels and other flattened fields.
  • Act on issues. Workflow nodes create_jira_ticket (project, issue type, summary, description, priority, labels) and jira_update (transition, comment, add_label, remove_label); the adapter also supports transition-to-done and status lookups. Comments are written as Atlassian Document Format.
  • Metadata for forms. Projects, issue types and statuses per project (GET /api/jira/connections/{connection_id}/projects, .../issue-types, .../statuses) feed the node configuration UI; fetch-issue wraps a real issue as a synthetic webhook payload for the workflow canvas Test tab.
  • Scheduled issues carry front matter. When a schedule creates a Jira issue “for an agent”, the description starts with a YAML front matter block (agent, schedule id, repositories). There is no per-connection trigger setting: Jira events reach agents only through workflows with a JIRA Event (jira_event) trigger on the connection.
  • Platform side. The Atlassian OAuth app (client id and secret, webhook secret) is configured once in the admin app (/integrations/jira, /api/admin/jira/config).

​
Who can use it

  • Connect (GET /api/jira/connect), verify, disconnect and register webhooks (choosing monitored projects): editor or admin (ability integration.manage, listed under Settings -> Roles, /settings/roles). A viewer gets 403 EDITOR_REQUIRED; the page shows “Only editors and admins can change this integration.” next to the action.
  • List connections, browse projects, issue types and statuses, fetch an issue for the Test tab, view deliveries: any company member.
  • Platform Jira app configuration: platform admin.
  • No plan or tier gate.

​
How to configure it

  1. A platform admin sets the Atlassian app credentials once (PUT /api/admin/jira/config).
  2. Settings -> Integrations (/integrations) -> Jira -> Connect (/api/jira/connect), approve at Atlassian within ten minutes; you return to the connection’s Status tab.
  3. Projects tab: choose the monitored projects and register the webhook (POST /api/jira/connections/{connection_id}/webhooks).
  4. To have Jira events reach an agent, build a workflow with a JIRA Event (jira_event) trigger on this connection, for example jira_event -> create_task -> dispatch_task; use the Test tab’s “fetch issue” to try it with real data.
  5. POST .../verify checks the token and site; DELETE /api/jira/connections/{id} disconnects (and marks open issue links as errored).

​
Limits and defaults

​
What it emits

  • Workflow runs for matched events; webhook delivery and dedup records.
  • Issues, comments, labels and transitions in Jira created by workflow nodes or schedules.
  • last_webhook_at, last_error and status on the connection.

​
Known gaps

  • A Jira issue never becomes a task by itself: the webhook handler only starts workflows. The GitHub integration turns labelled issues into tasks directly; Jira needs a workflow with jira_event -> create_task -> dispatch_task. Scheduled Jira issues “for an agent” therefore have no consumer unless such a workflow exists.
  • No issue search (JQL) in the adapter, so duplicates cannot be detected before create_jira_ticket.
  • No Jira Data Center or Server support; Cloud only.
  • Cloud tasks have no Jira access of their own; only server-side workflow nodes use the connection’s token.

​
Customer-safe summary

Connect your Jira Cloud site with a single sign-in and choose which projects Olyros watches. Issue creation, status changes and label changes in those projects can start your automations, and automations can create issues, comment, add labels and move issues between statuses. Olyros keeps the connection healthy by refreshing the credentials and the webhook on its own, and shows you every event it received.