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"]
origin:
  type: upstream
upstream:
  repository: grandcamel/JIRA-Assistant-Skills
  path: skills/jira-jsm
  ref: b5837311ca3ae61ac56dab8fe9c0d9a4e075c092
  license: MIT
trust:
  tier: reviewed
  reviewed_at: '2026-08-26'
  reviewed_by: ulises-jeremias
  reviewed_provenance: sha256:e78f6f614e730d93dba0fcecae6548e7acc9907090fbf76c401631f27aa03c6d
maintenance:
  status: active
  last_checked: '2026-08-26'
distribution:
  mode: vendored
  redistribution_allowed: true
  attribution_file: LICENSE
security:
  scripts: false
  shell: false
  network: true
  mcp: false
  hooks: false
---

# 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](references/DECISION_TREE.md)

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

```bash
# 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](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:

```bash
# 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

```bash
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](references/CONFIG_REFERENCE.md).

## Finding Service Desk IDs

Service desk IDs are numeric identifiers required by most scripts.

```bash
# 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:
```bash
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"
```bash
jira-as jsm service-desk list  # Find correct ID
```

### "Authentication failed"
Verify environment variables and API token. See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).

### "SLA information not available"
Verify SLA is configured in JSM project settings.

For all troubleshooting scenarios, see [docs/TROUBLESHOOTING.md](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](references/DATACENTER_GUIDE.md).

## Detailed Documentation

| Topic | Location | When to Read |
|-------|----------|--------------|
| Getting started | [docs/QUICK_START.md](docs/QUICK_START.md) | First time using jira-jsm |
| Usage examples | [docs/USAGE_EXAMPLES.md](docs/USAGE_EXAMPLES.md) | Looking for code examples |
| ITIL workflows | [docs/ITIL_WORKFLOWS.md](docs/ITIL_WORKFLOWS.md) | Incident/change/problem workflows |
| Troubleshooting | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Encountering errors |
| Best practices | [docs/BEST_PRACTICES.md](docs/BEST_PRACTICES.md) | Improve service desk operations |
| Rate limits | [references/RATE_LIMITS.md](references/RATE_LIMITS.md) | HTTP 429 errors |
| API reference | [references/API_REFERENCE.md](references/API_REFERENCE.md) | Building integrations |
| Configuration | [references/CONFIG_REFERENCE.md](references/CONFIG_REFERENCE.md) | Multi-instance setup |
| Decision tree | [references/DECISION_TREE.md](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](https://developer.atlassian.com/cloud/jira/service-desk/rest/intro/)
- [JSM Assets REST API](https://developer.atlassian.com/cloud/insight/rest/intro/)
- [ITIL Framework](https://www.axelos.com/certifications/itil-service-management)