jira-service-management
jira-jsm
Complete ITSM (IT Service Management) and ITIL workflow support for Jira Service Management (JSM).
Risk Levels
| Operation | Risk | Notes |
|---|---|---|
| List service desks/queues | - |
Read-only |
| Get request/SLA status | - |
Read-only |
| Search knowledge base | - |
Read-only |
| List customers/orgs | - |
Read-only |
| Create request | - |
Easily reversible (can cancel) |
| Add comment (public) | - |
Can delete |
| Add comment (internal) | - |
Can delete |
| Create customer | - |
Can remove |
| Create organization | - |
Can delete |
| Create asset | - |
Can delete |
| Transition request | ! |
Can transition back |
| Add participant | ! |
Can remove |
| Update asset | ! |
Can update again |
| Link asset to request | ! |
Can unlink |
| Approve request | ! |
Cannot unapprove (audit trail) |
| Decline request | ! |
Cannot undecline (audit trail) |
| Remove customer | !! |
Loses service desk access |
| Delete organization | !! |
Customer associations lost |
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 standardPROJ-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:
| Capability | Description | Key Commands |
|---|---|---|
| Service Desk Core | Manage service desks, portals, request types | jira-as jsm service-desk list, jira-as jsm request-type fields |
| Request Management | Create and manage customer-facing requests | jira-as jsm request create, jira-as jsm request get, jira-as jsm request transition |
| Customer & Organization | Manage customers, organizations, participants | jira-as jsm customer create, jira-as jsm request add-participant |
| SLA & Queue | Track SLAs, manage queues | jira-as jsm sla get, jira-as jsm sla report, jira-as jsm queue list |
| Comments & Approvals | Collaboration and approval workflows | jira-as jsm request comment, jira-as jsm approval approve |
| Knowledge Base & Assets | KB search, asset management | jira-as jsm kb search, jira-as jsm kb suggest, jira-as jsm asset create |
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 (--summary is required, --description is optional)
jira-as jsm request create 1 10 --summary "Email service down" --description "Production email server is not responding to connections"
# 3a. Create request on behalf of a customer (requires account ID, not email)
jira-as jsm request create 1 10 --summary "Password reset" --on-behalf-of "5b10ac8d82e05b22cc7d4ef5"
# 3b. Preview request creation without executing (dry-run)
jira-as jsm request create 1 10 --summary "Test request" --dry-run
# 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
jira-as jsm approval approve SD-124 --approval-id 1001 --yes
# 8. Preview approval without executing (dry-run)
jira-as jsm approval approve SD-124 --approval-id 1001 --dry-run
# 9. Decline a pending request
jira-as jsm approval decline SD-124 --approval-id 1001 --yes
# 9a. Preview decline without executing (dry-run)
jira-as jsm approval decline SD-124 --approval-id 1001 --dry-run
For detailed setup instructions, see docs/QUICK_START.md.
Available Commands
All commands support --help for full documentation.
Service Desk Core
| Command | Description |
|---|---|
jira-as jsm service-desk create |
Create new service desk |
jira-as jsm service-desk list |
List all service desks |
jira-as jsm service-desk get |
Get service desk details |
jira-as jsm request-type list |
List available request types |
jira-as jsm request-type get |
Get request type details |
jira-as jsm request-type fields |
Get custom fields for request type |
Request Management
| Command | Description |
|---|---|
jira-as jsm request create |
Create service request |
jira-as jsm request get |
Get request details |
jira-as jsm request status |
Get request status/lifecycle |
jira-as jsm request transition |
Transition request through workflow |
jira-as jsm request list |
List requests with filtering |
Customer Management
| Command | Description |
|---|---|
jira-as jsm customer create |
Create new customer |
jira-as jsm customer list |
List service desk customers |
jira-as jsm customer add |
Add customer to service desk |
jira-as jsm customer remove |
Remove customer from service desk |
jira-as jsm request add-participant |
Add participant to request |
jira-as jsm request remove-participant |
Remove participant from request |
jira-as jsm request participants |
List request participants |
Organization Management
| Command | Description |
|---|---|
jira-as jsm organization create |
Create customer organization |
jira-as jsm organization list |
List all organizations |
jira-as jsm organization get |
Get organization details |
jira-as jsm organization delete |
Delete organization |
jira-as jsm organization add-customer |
Add customer to organization |
jira-as jsm organization remove-customer |
Remove customer from organization |
SLA & Queue Management
| Command | Description |
|---|---|
jira-as jsm sla get |
Get SLA information for request |
jira-as jsm sla check-breach |
Check for SLA breaches |
jira-as jsm sla report |
Generate SLA compliance report |
jira-as jsm queue list |
List service desk queues |
jira-as jsm queue get |
Get queue details |
jira-as jsm queue issues |
Get requests in queue |
Comments & Approvals
| Command | Description |
|---|---|
jira-as jsm request comment |
Add comment to request |
jira-as jsm request comments |
Get request comments |
jira-as jsm approval list |
Get approval status for request |
jira-as jsm approval pending |
List pending approvals |
jira-as jsm approval approve |
Approve request |
jira-as jsm approval decline |
Decline request |
Knowledge Base & Assets
| Command | Description |
|---|---|
jira-as jsm kb search |
Search knowledge base articles |
jira-as jsm kb get |
Get knowledge base article |
jira-as jsm kb suggest |
Get KB article suggestions for request |
jira-as jsm asset create |
Create new asset |
jira-as jsm asset list |
List assets |
jira-as jsm asset get |
Get asset details |
jira-as jsm asset update |
Update asset attributes |
jira-as jsm asset link |
Link asset to request |
jira-as jsm asset find-affected |
Find assets affected by request |
Common Options
All scripts support these common options:
| Option | Description | Example |
|---|---|---|
--help |
Show help and exit | jira-as <command> --help |
--output FORMAT |
Output format: text, json, table | --output json |
--service-desk ID |
Service desk ID (numeric) | --service-desk 1 |
Exit Codes
| Code | Meaning | Description |
|---|---|---|
| 0 | Success | Operation completed |
| 1 | General Error | Unspecified error |
| 2 | Validation Error | Invalid input parameters |
| 3 | Authentication Error | Invalid or expired API token |
| 4 | Permission Error | User lacks permissions |
| 5 | Not Found | Resource not found |
| 6 | Conflict Error | Duplicate or state conflict |
| 7 | Rate Limit Error | API limit exceeded |
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:
| Skill | Integration | Example |
|---|---|---|
| jira-issue | CRUD operations | Update priority, assignee, labels |
| jira-lifecycle | Workflow transitions | Transition through approval workflow |
| jira-search | Query and filter | Find high-priority incidents, SLA breaches |
| jira-relationships | Link requests | Link incident to problem |
| jira-collaborate | Comments, attachments | Add rich comments, attach files |
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
| Tier | Features |
|---|---|
| JSM Standard | Service desks, requests, customers, SLAs, approvals, queues, KB |
| JSM Premium | Advanced SLA reporting, change management, problem management, CMDB |
| JSM Assets | Asset management, discovery, linking (free for up to 100 assets) |
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
| Topic | Location | When to Read |
|---|---|---|
| Getting started | docs/QUICK_START.md | First time using jira-jsm |
| Usage examples | docs/USAGE_EXAMPLES.md | Looking for code examples |
| ITIL workflows | docs/ITIL_WORKFLOWS.md | Incident/change/problem workflows |
| Troubleshooting | docs/TROUBLESHOOTING.md | Encountering errors |
| Best practices | docs/BEST_PRACTICES.md | Improve service desk operations |
| Rate limits | references/RATE_LIMITS.md | HTTP 429 errors |
| API reference | references/API_REFERENCE.md | Building integrations |
| Configuration | references/CONFIG_REFERENCE.md | Multi-instance setup |
| Decision tree | references/DECISION_TREE.md | Choosing the right skill |
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
More from grandcamel/jira-assistant-skills
jira-agile-management
Epic creation and sprint management - create epics, manage sprints, view backlog, estimate with story points. TRIGGERS: 'create an epic', 'create epic', 'new epic', 'show the backlog', 'view backlog', 'add to sprint', 'move to sprint', 'set story points', 'sprint planning', 'epic for', 'link to epic', 'sprint list', 'active sprint', 'velocity', 'create subtask'. NOT FOR: bugs/tasks/stories without epic context (use jira-issue), field ID discovery (use jira-fields), searching issues by JQL (use jira-search), transitioning issues through workflow (use jira-lifecycle).
10jira-search-jql
Find issues by criteria (status, assignee, priority, etc.) using JQL. Create filters, export results to CSV/JSON, bulk update. Ideal for reporting and automation.
7jira-administration
>
5jira-developer-integration
Git and developer workflow integration. TRIGGERS: 'generate branch name', 'create branch name', 'branch name for', 'write PR description', 'PR description for', 'link PR', 'link pull request', 'parse commit', 'extract issue from commit', 'smart commit', 'development panel'. Use for Git, GitHub, GitLab, Bitbucket integration with JIRA. NOT FOR: issue field updates (use jira-issue), searching issues (use jira-search), status transitions (use jira-lifecycle).
4jira-assistant
JIRA automation hub routing to 13 specialized skills for any JIRA task: issues, workflows, agile, search, time tracking, service management, and more.
3jira-operations
JIRA cache and performance operations. TRIGGERS: 'warm the cache', 'warm cache', 'cache status', 'clear cache', 'cache warm', 'cache for project', 'discover project', 'project discovery', 'cache hit rate', 'optimize performance', 'rate limit'. Use for JIRA API performance optimization and project context discovery. NOT FOR: project configuration/settings (use jira-admin), issue operations (use jira-issue), bulk issue modifications (use jira-bulk).
3