shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

"jira-service-management"

为JSM提供完整的ITSM/ITIL工作流支持 - 服务台、请求、SLA、客户、审批、知识库。在管理服务台请求、跟踪SLA或处理客户操作时使用。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

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

| 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 current request status and category | | 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 |

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:

| Option | Description | Example | |--------|-------------|---------| | --help | Show help and exit | jira-as jsm <command> --help | | -o, --output FORMAT | Output format: text (default) or json; organization list and sla report also accept csv | -o json | | --dry-run | Preview a mutating command without executing it | jira-as jsm request create 1 10 --summary "Test" --dry-run |

Exit Codes

| Code | Meaning | Description | |------|---------|-------------| | 0 | Success | Operation completed | | 1 | General/Validation Error | Invalid input or unspecified error | | 2 | Authentication Error | Invalid or expired API token | | 3 | Permission Error | User lacks permissions | | 4 | Not Found | Resource not found | | 5 | Rate Limit Error | API limit exceeded | | 6 | Conflict Error | Duplicate or state conflict | | 7 | Server Error | JIRA server-side error (5xx) | | 130 | Cancelled | Interrupted with Ctrl+C |

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:

| 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