Jira Service Management

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 (--summary is optional; some request types derive it from other fields)
jira-as jsm request create 1 10 --summary "Email service down" --description "Production email server is not responding to connections"

# 3a. Create with priority and labels
jira-as jsm request create 1 10 --summary "VPN outage" --priority High --labels "network,urgent"

# 3b. 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"

# 3c. Preview request creation without executing (dry-run); use -o json for machine-readable output
jira-as jsm request create 1 10 --summary "Test request" --dry-run
jira-as jsm request create 1 10 --summary "Test request" -o json

# 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

# 6a. Post a customer-visible comment in Jira wiki markup
jira-as jsm request comment SD-123 "*Root cause* identified — fix in progress. See {{KB-42}} for the workaround." --format wiki

# 6b. Preview a comment without posting it
jira-as jsm request comment SD-123 "Draft reply" --dry-run

# 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

Request Management

Customer Management

Organization Management

SLA & Queue Management

Comments & Approvals

Knowledge Base & Assets

Behavior Notes

Request Types and Issue Types

Every JSM request type is backed by a standard JIRA issue type:

# Show the underlying JIRA issue type for each request type
jira-as jsm request-type list 1 --show-issue-types

# Discover which fields a request type accepts through the API
jira-as jsm request-type fields 1 10

• --summary is optional on request create — some request types derive the summary from other fields.
• If request create fails with a field error, run request-type fields first: the JSM request API only accepts the fields configured on that request type's portal form, and some portal-only widgets (e.g., Assets/CMDB object pickers) cannot be populated through --fields.
• Portal bypass: because JSM requests are standard JIRA issues, jira-as issue create with the bound issue type can create the issue directly when the API accepts those fields. The result may lack a request type and portal context (it will not appear as a customer-facing portal request), so prefer jsm request create for customer-facing requests.

Customer Comments

jira-as jsm request comment sends the body verbatim in both formats; --format wiki declares that the body is Jira wiki markup so the portal renders the formatting. JSM comments are never converted to ADF.

Output Shapes

• jira-as jsm request status prints the current status and its category (JSON: {"status": ..., "statusCategory": ...}), not a status history.
• jira-as jsm request comments and jira-as jsm request participants print plain JSON arrays with -o json — the JSM API's paginated values envelope is unwrapped for you.

Common Options

Most commands support these options:

Exit Codes

Configuration

Environment Variables

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

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