Integrating Jira Service Management with Your Scripts

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

Two patterns for Jira Service Management integrations

Most Jira Service Management integrations come down to two directions of data flow: something in your stack needs to push work into the service desk, or the service desk needs to trigger something in your stack. You can build both with a CLI and a few lines of shell, no REST client required. atlassian-cli is the glue: any tool that can run a shell command (a monitor, a chat bot, a CI job, a webhook handler) can now read and write JSM.

The outbound pattern is a script calling the CLI to create or update requests, for example a Prometheus alert opening an incident ticket. The inbound pattern is JSM firing a webhook at an endpoint you control, whose handler shells out to the CLI to comment, transition, or route the request. Everything below uses verified jsm subcommands. Check them against the full command reference before you adapt them.

Outbound: turn events into requests

The building block for every outbound integration is jsm request create. It takes the numeric service desk ID and request type ID, plus a summary and description. You can find those IDs once and hard-code them, or discover them dynamically.

# Discover the service desks and their IDs
atlassian-cli jsm service-desk list --limit 25

# List request types for service desk 10
atlassian-cli jsm request-type list --servicedesk-id 10 --limit 25

With the IDs in hand, opening a request from any script is one command. Here a monitoring alert opens an incident:

# A monitor fires: open a JSM request and capture the key
KEY=$(atlassian-cli jsm request create \
  --servicedesk-id 10 \
  --request-type-id 7 \
  --summary "Disk usage critical on db-01" \
  --description "Root volume at 96%. Alert from Prometheus rule DiskFull." \
  --format json | jq -r '.issueKey // .key')

echo "Opened $KEY"

Because the CLI can emit --format json, you capture the new request key and reuse it in the same script to comment, add participants, or transition. That single property, structured output, is what turns a one-off command into a real integration. The --format flag accepts table, json, csv, yaml, quiet, and markdown, so the same command feeds a dashboard, a spreadsheet, or a CI gate depending on how you call it.

One thing worth handling early: avoid opening a duplicate request every time a noisy alert re-fires. Before creating, run a quick jsm request list --servicedesk-id 10 --format json and check whether an open request already references the same host or alert ID. If it does, comment on the existing key instead of creating a new one. That single guard keeps your queue clean when a flapping check fires ten times in an hour.

Comment, transition, and route requests from code

Once a request exists, integrations spend most of their time updating it. The CLI mirrors the actions an agent would take in the portal, so a script can acknowledge a reporter, move the request through the workflow, and pull in the right responder.

# Post a public reply the customer can see
atlassian-cli jsm request add-comment SD-123 \
  --body "Thanks, we are investigating and will update within 30 minutes." \
  --public

# Post an internal-only note (omit --public)
atlassian-cli jsm request add-comment SD-123 \
  --body "Paged on-call via the alert integration."

# Inspect the available transitions, then move the request
atlassian-cli jsm request transitions SD-123
atlassian-cli jsm request transition SD-123 --transition "In Progress"

# Add the responding engineer as a participant
atlassian-cli jsm request add-participant SD-123 --account-id 5f0a1b2c3d

The --public flag on add-comment is the difference between a customer-facing reply and an internal note, which matters when a bot is posting on behalf of your team. Always call jsm request transitions first to read the exact transition names for that request type, since workflow names vary between projects and a wrong string will fail the command.

Need the current state before deciding what to do? jsm request status SD-123 returns the request status, and jsm request get SD-123 returns the full object. Pipe either through jq to branch your automation on the result.

Watch SLAs and escalate before they breach

The most valuable JSM integrations act on SLAs, not just tickets. The CLI exposes the same SLA metrics the portal shows, so a scheduled job can read the remaining time on a request and escalate before a target is missed.

# List all SLA metrics on a request
atlassian-cli jsm sla list SD-123 --format json

# Read one specific SLA, e.g. time to resolution
atlassian-cli jsm sla get SD-123 --sla-id time-to-resolution --format json

Inspect the JSON once to find the field that holds remaining time for your instance, then branch on it. A cron job can walk an open queue and act on anything close to breach:

# Nightly: export the open queue, check SLAs, escalate
atlassian-cli jsm queue issues 10 5 --format csv > open-queue.csv

# For a flagged request, add the incident manager and comment
atlassian-cli jsm request add-participant SD-123 --account-id 6a1b2c3d4e
atlassian-cli jsm request add-comment SD-123 \
  --body "SLA approaching breach, escalated to incident manager."

The queue commands (jsm queue list 10, jsm queue get 10 5, and jsm queue issues 10 5) take the numeric service desk ID followed by the queue ID, and they page automatically so you get every matching request regardless of count.

Inbound: webhook handlers that call the CLI

Inbound integrations start with a webhook you register on the Atlassian side (through JSM automation or site administration) that points at an HTTP endpoint you own. When a request is created or updated, JSM sends a JSON payload to your endpoint. Your handler reads the request key from that payload and shells out to the CLI to act on it.

You do not configure the webhook itself from the CLI, but you can audit which webhooks a site already has so integrations do not step on each other:

# List webhooks registered on the site (JSM runs on Jira)
atlassian-cli jira webhooks list

A minimal handler is just a few lines. Whatever runs your endpoint (a serverless function, a small server, or a queue worker) can call the same commands you would run by hand:

#!/bin/bash
# webhook-handler.sh: called with the JSM payload on stdin
set -euo pipefail
# Unattended runs assume no default profile: pass --profile on every command

PAYLOAD=$(cat)
KEY=$(echo "$PAYLOAD" | jq -r '.issue.key')

# Auto-acknowledge every newly created request
atlassian-cli jsm request add-comment "$KEY" \
  --body "Received. A team member will respond shortly." \
  --public --profile prod

# Route hardware requests straight to In Progress
if echo "$PAYLOAD" | jq -e '.issue.fields.summary | test("hardware"; "i")' > /dev/null; then
  atlassian-cli jsm request transition "$KEY" --transition "In Progress" --profile prod
fi

This is the whole point of using a CLI as an integration layer: the same commands work interactively, in a cron job, and inside a webhook handler. There is no SDK to version, no OAuth dance to reimplement per language, and no difference between what you test by hand and what runs in production.

Auth for unattended scripts

Integrations run without a human present, so authentication has to be non-interactive. Set up a named profile once, then reference it in every command or through the --profile flag.

# One-time interactive setup on a trusted machine
atlassian-cli auth login

# Verify the session in CI without printing anything
atlassian-cli auth test --profile prod --format quiet && echo OK

# Use the profile in an integration command
atlassian-cli jsm request list --servicedesk-id 10 --limit 25 --profile prod

The --format quiet mode sets an exit code and prints nothing, which makes it ideal for a CI gate: the pipeline stops if credentials are missing or expired. For per-environment separation, keep one profile for staging and one for production so a test script can never touch a live service desk. The full setup, including token storage and CI environment variables, is covered in the authentication guide.

Integration recipes reference

A quick map from a common trigger to the CLI command that handles it. Every command below is a real subcommand you can verify in the reference.

For a broader tour of the service desk commands (customers, organizations, approvals, and request types), see the JSM CLI guide. If you would rather work against the endpoints directly, the Jira Service Management API walkthrough covers the raw calls the CLI wraps. And to surface help-center answers inside these flows, the JSM knowledge base from the CLI post shows how jsm kb search fits in.

FAQ

Related Resources