home / skills / grandcamel / jira-assistant-skills / jira-jsm

jira-jsm skill

safe

/skills/jira-jsm

This skill helps you manage Jira Service Management ITSM workflows, SLAs, and approvals from a unified CLI interface.

npx playbooks add skill grandcamel/jira-assistant-skills --skill jira-jsm

Review the files below or copy the command above to add this skill to your agents.

Files (13)

SKILL.md

13.5 KB

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

```bash
export JIRA_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-api-token"

# Optional: Default service desk
export JSM_DEFAULT_SERVICE_DESK="1"
```

### Profile Support

```bash
```

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)

Overview

This skill provides end-to-end ITSM and ITIL support for Jira Service Management (JSM), handling service desks, customer requests, SLAs, approvals, knowledge base searches, and assets. It exposes a CLI-driven workflow (jira-as jsm) for safe, auditable operations that map to real-world service desk tasks. Use it to automate request lifecycle, track SLA compliance, and manage customer and asset relationships.

How this skill works

The skill operates via the jira-as CLI and organizes functionality into service desk core, request management, customer/organization operations, SLA and queue tools, comments and approvals, and knowledge base and asset management. Commands are mostly safe read or reversible actions; a risk table highlights operations that are cautionary or potentially destructive. Configure with standard Jira credentials via environment variables and run commands with --help for usage details.

When to use it

Managing customer-facing incidents, service requests, changes, or approvals in a JSM project
Tracking SLA status, detecting breaches, or generating SLA compliance reports
Automating request creation, transitions, comments, or participant updates
Linking assets to requests or performing impact analysis with the asset inventory
Integrating KB suggestions into request triage or providing self-service search

Best practices

Always use the jira-as CLI entrypoint; avoid running internal scripts directly
Store common service desk IDs and profile values in environment variables
Prefer dry-run flags for approvals, transitions, or create operations when testing
Limit destructive actions (remove customer, delete org) and verify permissions first
Use approval and audit commands for traceability; approvals are recorded and not reversible

Example use cases

Create an incident request on behalf of a customer and add Tier 2 as an internal participant
Check SLA status for a high-priority service desk ticket and list potential breaches
Approve or decline a pending change request from the CLI with dry-run preview
Search the knowledge base and attach suggested KB articles to a customer response
Link an affected asset to a request and update asset attributes during triage

FAQ

How do I find service desk IDs?

Run jira-as jsm service-desk list or jira-as jsm service-desk get <id>; store frequent IDs in env vars.

Can I reverse an approval?

Approvals are audited and cannot be unapproved; use caution and dry-run to preview actions.

What environment variables are required?

Set JIRA_URL, JIRA_EMAIL, and JIRA_API_TOKEN. Optionally set JSM_DEFAULT_SERVICE_DESK for defaults.