jira-service-management

name	jira-service-management
description	Complete ITSM/ITIL workflow support for JSM - service desks, requests, SLAs, customers, approvals, knowledge base. Use when managing service desk requests, tracking SLAs, or handling customer operations.
version	1.0.0
author	jira-assistant-skills
license	MIT
allowed-tools	["Bash","Read","Glob","Grep"]

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 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:

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="[e-mail]"
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

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