Using Jira Cloud

Practical guide for working with Jira issues, boards, sprints, and projects through Fp Switchboard.

Quick Tips

• Use JQL for powerful searches: project = "PROJ" AND status = "In Progress" ORDER BY priority DESC
• Issue keys are PROJECT-NUMBER format (e.g., DEV-123) — never guess, always search first
• Descriptions and comments use ADF (Atlassian Document Format) — send markdown, Switchboard converts automatically
• Transitions must use the transition name, not an ID
• Board and sprint operations use the Agile REST API, not the standard API

Common Gotchas

JQL Syntax Matters Critical

Text values with spaces need quotes. Use = for exact match, ~ for contains.

	Example
Wrong	status = In Progress
Correct	status = "In Progress"

Error: Error in the JQL Query: Expecting either...

Issue Keys vs Numeric IDs Critical

Always use issue keys (PROJECT-123) not numeric IDs. Keys are human-readable and stable across moves.

	Example
Wrong	jira_get_issue({issue_id: "10042"})
Correct	jira_get_issue({issue_key: "DEV-123"})

Transitions by Name, Not ID Critical

Use the human-readable transition name. The system resolves to the correct transition ID automatically.

	Example
Wrong	jira_transition_issue({transition: "31"})
Correct	jira_transition_issue({transition: "In Progress"})

Available transitions are shown in the error message if the name doesn’t match.

ADF Handled Automatically Important

Jira v3 API requires Atlassian Document Format for rich text. Send plain text or markdown — Fp Switchboard converts automatically.

	Example
Wrong	Manually constructing ADF JSON
Correct	Just send markdown: "## Summary\n\nThis is **bold** text"

Board IDs Are Not Project Keys Important

Boards have numeric IDs separate from project keys. Use jira_list_boards to find the right board ID.

Sprint Scope Is Per-Board Important

Sprints belong to boards, not projects. A project may have multiple boards with different sprints.

	Example
Wrong	jira_list_sprints({project: "DEV"})
Correct	jira_list_boards() → jira_list_sprints({board_id: "42"})

Multi-Step Patterns

Sprint Planning

1. jira_list_boards to find the right board
2. jira_create_sprint with name and dates
3. jira_search to find backlog issues
4. jira_move_to_sprint to add issues

Issue Workflow

1. jira_list_projects to get project key
2. jira_list_issue_types to get valid types
3. jira_create_issue with project, type, summary
4. jira_transition_issue to move through workflow

Bulk Triage

1. jira_search with JQL to find unassigned issues
2. jira_search_users to find assignees
3. jira_assign_issue for each issue
4. jira_add_labels to categorize

ID Format Reference

ID Type	Format	Example
Issue Key	PROJECT-NUMBER	DEV-123
Project Key	UPPERCASE (2-10)	PROJ
Board ID	Integer	42
Sprint ID	Integer	7
Account ID	Hex string (24)	5b10ac8d82e05b22cc7d4ef5

JQL Quick Reference

Query	Description
assignee = currentUser()	My issues
status = "In Progress"	Active work
project = "KEY" AND type = Bug	Bugs in a project
sprint in openSprints()	Current sprint issues
updated >= -7d ORDER BY updated DESC	Recently updated
priority = Highest AND status != Done	Urgent open items
labels = "frontend" AND fixVersion = "2.0"	Filtered by label and version

Example Prompts

• “Show my open Jira issues”
• “Create a bug in the DEV project about the login error”
• “Move DEV-123 to In Progress”
• “List sprints on the main board”
• “Search for unassigned high-priority issues”
• “Add a comment to PROJ-456 about the fix”

Rate Limits

Limit	Value
Requests per minute	~100
Best practice	Use JQL search instead of individual fetches