jira-jsm

Complete ITSM (IT Service Management) and ITIL workflow support for Jira Service Management (JSM).

Risk Levels

Risk Legend: - Safe, read-only | ! Caution, modifiable | !! Warning, destructive but recoverable | !!! Danger, irreversible

When to use this skill

Use jira-jsm when you encounter:

Problem Indicators

• Keywords: “SLA”, “service level”, “breach”, “approval”, “change request”, “incident”
• Issue keys like: SD-123, INC-456 (service desk format vs standard PROJ-123)
• Workflow needs: customer-facing requests, ITIL processes, service catalogs
• User questions about: incidents, problems, changes, service requests (not bugs/stories)

Feature Triggers

• Need to track SLA compliance or generate SLA reports
• Managing approval workflows or CAB (Change Advisory Board) decisions
• Working with knowledge base integration for customer self-service
• Linking IT assets to requests or impact analysis
• Multi-tier support structure (agents, managers, customers)

Integration Scenarios

• Created a request and want to update it: Use jira-issue for standard updates
• Transitioning through approval workflow: Use jira-jsm for JSM-specific transitions
• Searching for requests with complex criteria: Use jira-search for JQL

NOT This Skill

• Creating bugs/stories in Agile: Use jira-issue
• Sprint planning or backlog management: Use jira-agile
• Developer workflow integration: Use jira-dev
• Standard issue lifecycle management: Use jira-lifecycle

Still unsure? Check the decision tree

What this skill does

IMPORTANT: Always use the jira-as CLI. Never run Python scripts directly.

This skill provides comprehensive JSM operations organized into 6 key ITSM capabilities:

Quick Start

# 1. List service desks to find your ID
jira-as jsm service-desk list

# 2. List request types for your service desk
jira-as jsm request-type list 1

# 3. Create an incident (both summary AND description are required)
jira-as jsm request create 1 10 --summary "Email service down" --description "Production email server is not responding to connections"

# 4. Check SLA status
jira-as jsm sla get SD-123

# 5. Add a comment to a request (body is positional, before flags)
jira-as jsm request comment SD-123 "Looking into this issue now"

# 6. Add an internal comment (agent-only, not visible to customers)
jira-as jsm request comment SD-123 "Escalating to Tier 2 support" --internal

# 7. Approve a pending request (issue_key, approval_id)
jira-as jsm approval approve SD-124 1001 --comment "Approved" --yes

# 8. Preview approval without executing (dry-run)
jira-as jsm approval approve SD-124 1001 --dry-run

For detailed setup instructions, see docs/QUICK_START.md.

Available Commands

All commands support --help for full documentation.

Service Desk Core

Request Management

Customer Management

Organization Management

SLA & Queue Management

Comments & Approvals

Knowledge Base & Assets

Common Options

All scripts support these common options:

Exit Codes

Configuration

Environment Variables

export JIRA_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"

# Optional: Default service desk
export JSM_DEFAULT_SERVICE_DESK="1"

Profile Support

For full configuration options, see references/CONFIG_REFERENCE.md.

Finding Service Desk IDs

Service desk IDs are numeric identifiers required by most scripts.

# Method 1: List all service desks
jira-as jsm service-desk list

# Method 2: Get details by ID
jira-as jsm service-desk get 1

Tip: Store frequently used IDs in environment variables:

export IT_SERVICE_DESK=1
export HR_SERVICE_DESK=2

Integration with Other Skills

JSM requests (SD-* keys) are standard JIRA issues and work with all skills:

Troubleshooting

“Service desk not found”

jira-as jsm service-desk list  # Find correct ID

“Authentication failed”

Verify environment variables and API token. See docs/TROUBLESHOOTING.md.

“SLA information not available”

Verify SLA is configured in JSM project settings.

For all troubleshooting scenarios, see docs/TROUBLESHOOTING.md.

License Requirements

Version Compatibility

• JIRA Cloud: Fully supported (primary target)
• JIRA Data Center 9.0+: Supported with minor differences
• JIRA Data Center 8.x: Partial support

For Data Center specifics, see references/DATACENTER_GUIDE.md.

Detailed Documentation

Related Skills

• jira-issue – Standard issue CRUD operations
• jira-lifecycle – Workflow transitions and status management
• jira-search – JQL searches and filters
• jira-collaborate – Comments, attachments, watchers, notifications
• jira-relationships – Issue linking (incidents to problems)
• shared – Common utilities, authentication, error handling

References

• JSM Cloud REST API Documentation
• JSM Assets REST API
• ITIL Framework