Jira integration

Jira is an issue and project tracking platform used to plan, prioritize, and track work. Teams use it to create issues, organize sprints, collaborate in comments, automate workflows with transitions, and report on progress across projects.

Use cases

• Create and update Jira issues from forms, jobs, or backend workflows
• Power internal dashboards by searching issues with JQL
• Add comments or attachments to issues when backend events fire
• Trigger notifications and move issues through transitions programmatically

Setup

1. Create or retrieve an API token in Jira.
2. In WeWeb, add your Jira API credentials to both Editor and Production modes.
3. Test with the simplest possible action (e.g., Create Issue or a minimal JQL search) to verify authentication. Prefer test‑first when feasible.
4. If the test fails due to provider requirements, complete additional setup (e.g., adjust project permissions, enable scopes/permissions, configure webhooks or IP allowlists), then retry the same test.

TIP

Prefer OAuth 2.0 for end-user context across tenants. Use API token for server-to-server automation with a service account.

Common pitfalls (setup & usage)

Permissions mismatch (401/403)

Ensure the calling account has the right project permissions (Browse, Create/Edit issues, Add Comments, Add Attachments) and any required global permissions for the target projects.

Invalid ADF for descriptions/comments

Descriptions and comments must be valid ADF. Use a minimal ADF doc structure when generating content to avoid malformed payloads.

Attachments formatting

Attachments must be sent as multipart/form-data. Site policies may block some file types and enforce size limits.

Workflow transitions

Transitions are workflow-specific. Always fetch available transitions for the current status and pass the correct transitionId.

JQL validation and context

JQL can fail silently if invalid in context. During development, set validation on and test with minimal fields; avoid custom field names you can’t guarantee.

Rate limiting (429)

Under concurrency, you may encounter 429 responses. Use exponential backoff and jitter; avoid parallel write bursts.

All Actions

Short reference of available actions. Click an action to jump to its details.

Action	Description
Create Issue	Create a Jira issue
Search Issues	Find issues using JQL
Add Comment	Add a comment to an issue

Action details

Create Issue

Create a new issue in a specific project with a given issue type.

Inputs

Display Key	Example Input	Description	Restrictions
Project Key	"PROJ"	The key of the project	Must be a valid project key
Issue Type	"Bug"	The type of issue to create	Valid issue types: Bug, Task, Story, Epic
Summary	"Fix login error"	The summary/title of the issue	Must be non-empty string
Description Optional	{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Description text"}]}]}	The description of the issue in Atlassian Document Format	Must be valid ADF format
Priority Optional	"High"	The priority of the issue	Valid priorities: Highest, High, Medium, Low, Lowest
Assignee Optional	"5b10a2844c20165700ede21g"	The account ID of the user to assign	Must be a valid user account ID
Labels Optional	["bug","frontend"]	Array of labels to add to the issue	Array of strings
Components Optional	[{"name":"Backend"}]	Array of components	Array of component objects
Update Operations Optional	{}	Additional update operations	Object with field-specific operations

Example output

{
  "id": "10001",
  "key": "PROJ-123",
  "self": "https://your-domain.atlassian.net/rest/api/3/issue/10001",
  "fields": {
    "summary": "Fix login error",
    "issuetype": { "name": "Bug" },
    "status": { "name": "To Do" },
    "assignee": { "accountId": "5b10a2844c20165700ede21g" }
  }
}

Documentation of API endpoint that powers action: Jira Cloud REST API – Create issue (POST /rest/api/3/issue)

Search Issues

Find issues using JQL to power lists, dashboards, and automations.

Inputs

Display Key	Example Input	Description	Restrictions
JQL Query Optional	"project = PROJ AND status = "In Progress""	JQL query to filter issues	Must be valid JQL syntax
Start At Optional	0	The index of the first item to return	Non-negative integer
Max Results Optional	50	The maximum number of items to return	1–100; default 50
Fields Optional	["summary","status","assignee"]	Fields to include in response
Expand Optional	["names","schema"]	Additional data to include
Validate Query Optional	true	Whether to validate the JQL query

Example output

{
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    { "id": "10001", "key": "PROJ-123" }
  ]
}

Documentation of API endpoint that powers action: Jira Cloud REST API – Search issues (GET /rest/api/3/search)

Add Comment

Add a collaborative comment on an issue (ADF format supported).

Inputs

Display Key	Example Input	Description	Restrictions
Issue ID or Key	"PROJ-123"	The ID or key of the issue	Must be a valid issue identifier
Comment Body	{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"This is a comment"}]}]}	The comment content in Atlassian Document Format	Must be valid ADF format
Visibility Type Optional	"role"	Type of visibility restriction	role, group
Visibility Value Optional	"Administrators"	Role or group name for visibility	Must be valid role/group name
Properties Optional	[{"key":"sd.public.comment","value":{"internal":true}}]	Comment properties (e.g., internal comments)

Example output

{
  "id": "10001",
  "body": {
    "type": "doc",
    "version": 1,
    "content": [{"type": "paragraph", "content": [{"type": "text", "text": "This is a comment"}]}]
  },
  "created": "2025-10-21T10:00:00.000+0000"
}

Documentation of API endpoint that powers action: Jira Cloud REST API – Add comment (POST /rest/api/3/issue/{issueIdOrKey}/comment)

Error handling

Error code and type	Reason
401 Unauthorized	Invalid or missing API key or insufficient permissions.
400 Bad Request	Invalid parameters (e.g., malformed ADF, missing required fields).
429 Too Many Requests	Rate limiting encountered; reduce concurrency and retry with backoff.

FAQs

Why can’t I authenticate?

For API tokens, use Basic auth with your Atlassian account email and token against your site base URL. Ensure the user has permission on target projects. For OAuth, verify client, scopes, and redirect URIs.

What format should I use for dates and IDs?

Issue keys (e.g., PROJ-123) and account IDs are opaque. Date-time fields use ISO 8601 with timezone (e.g., 2025-10-15T10:00:00Z). Comments/descriptions accept ADF JSON.