Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 29 ยท Administration and Automation

Jira Automation and the REST API

Learn how Jira automation rules work (trigger, condition, action), how smart values fill messages, and how the REST API and webhooks connect Jira to other tools.

Much of the work around issues is repetitive: assign new bugs to the right person, move a parent to Done when the last subtask closes, post to chat when something becomes urgent. Jira can do these things for you with automation rules. When you need Jira to talk to other systems, such as a build server, a support desk or your own code, you use its REST API and webhooks.

This lesson covers both. The real Jira cannot run on this site, so rule screens are described in words, and API calls and JSON payloads are shown as read-only code. The runnable examples are stand-ins: a tiny JavaScript rule engine and a webhook receiver that work on sample data in your browser. They show the ideas, not Jira's implementation. When you write real integrations, always check Atlassian's current API reference, because endpoints and fields evolve.

Anatomy of a rule

Trigger The event that starts it.
Condition Only continue if this is true.
Action Do something to an issue or send a message.

When this happens, if that is true, then do this.

1 / 2

Automation rules: trigger, condition, action

An automation rule has a simple shape, often summarized as when - if - then:

  1. Trigger (when): the event that starts the rule. Examples: an issue is created, an issue is transitioned, a field value changes, a schedule fires, or a comment is added.
  2. Conditions (if): checks that decide whether the rule keeps going. Examples: the issue type is Bug, the priority is High, a JQL query matches.
  3. Actions (then): the work. Examples: assign the issue, edit a field, transition the issue, add a comment, create a subtask, send an email or a chat message, or call an external web address.

Here are three rules that save real time:

Rule Trigger Condition Action
Triage bugs Issue created Type = Bug Assign to the triage owner, add label needs-triage
Close the parent Issue transitioned All subtasks of the parent are Done Transition the parent to Done
Escalate Scheduled daily JQL: priority = Highest AND statusCategory != Done Send a chat message listing the issues

Rules run as an actor (by default an automation user), so activity in the issue history says who changed the issue. Every run is recorded in an audit log, which is the first place to look when a rule did not do what you expected.

A rule that edits an issue can fire the trigger of another rule, or of itself, and create a loop. Jira has limits on rule chains, but you should still design rules that make a change only once, for example by adding a condition such as "label does not contain needs-triage".

Smart values

Messages and field values inside actions can contain smart values: placeholders in double curly braces that Jira replaces when the rule runs. A few common ones:

TEXT
{{issue.key}}                  SHOP-42
{{issue.summary}}              Cart total ignores discount code
{{issue.assignee.displayName}} Ana Smith
{{issue.priority.name}}        Highest
{{now}}                        the current date and time

A comment action might read {{issue.key}} is {{issue.priority.name}} priority and needs a fix before the release. The exact list of available smart values depends on the trigger and on your Jira version.

A rule engine stand-in

The stand-in below represents rules as data (trigger name, a condition function and an action function) and runs them for incoming events, replacing smart values in a message template. It also records an audit log like Jira does.

JS A tiny automation rule engine (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first issue matches both rules; the second matches neither. Reading the audit log tells you exactly why, which is how you debug real rules too.

The REST API

Jira Cloud exposes almost everything you can do in the interface over an HTTP REST API that sends and receives JSON. Typical uses: create issues from a monitoring alert, update a status from a CI pipeline, export data for your own report, or sync with another system.

A request needs three things: the method and URL, authentication, and for writes a JSON body. For scripts, the usual pattern is the account email plus an API token sent with basic authentication; apps use OAuth. Never put tokens in source code or commit them; keep them in a secret store or environment variable.

The calls below are read-only illustrations of the common shapes (replace your-site with your site name, and verify details against the current reference, since API versions evolve):

Terminal
# Create an issue
curl --request POST \
  --url "https://your-site.atlassian.net/rest/api/3/issue" \
  --user "[email protected]:$JIRA_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data @new-issue.json
JSON
{
  "fields": {
    "project": { "key": "SHOP" },
    "issuetype": { "name": "Bug" },
    "summary": "Checkout returns an error",
    "labels": ["checkout"],
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        { "type": "paragraph", "content": [{ "type": "text", "text": "Steps to reproduce: ..." }] }
      ]
    }
  }
}

Version 3 of the API describes rich text in the Atlassian Document Format, a JSON tree of nodes like the doc and paragraph above, instead of plain strings. The response contains the new issue's id and key.

Moving an issue means choosing a transition id, not a status name, because ids are specific to the workflow:

Terminal
# 1. Which transitions are available for this issue?
curl --user "[email protected]:$JIRA_API_TOKEN" \
  "https://your-site.atlassian.net/rest/api/3/issue/SHOP-50/transitions"

# 2. Perform one (id taken from the previous answer)
curl --request POST --user "[email protected]:$JIRA_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "transition": { "id": "31" } }' \
  "https://your-site.atlassian.net/rest/api/3/issue/SHOP-50/transitions"

Searching uses JQL in a query parameter, and large result sets come back in pages, so loop until the response says there are no more. Respect the platform's rate limits: if a response says "too many requests", wait and retry rather than hammering the server.

Webhooks

With the API, your code asks Jira for things. A webhook reverses the direction: you give Jira a URL, and Jira sends an HTTP POST with a JSON payload whenever a chosen event happens (issue created, updated, deleted, sprint started, and more). That is much better than polling every minute.

A simplified payload looks like this (real payloads contain many more fields):

JSON
{
  "webhookEvent": "jira:issue_updated",
  "issue": {
    "key": "SHOP-50",
    "fields": { "summary": "Checkout returns an error", "status": { "name": "In Progress" } }
  },
  "changelog": {
    "items": [{ "field": "status", "fromString": "To Do", "toString": "In Progress" }]
  }
}

Your receiver should answer quickly (a 2xx status), do the slow work later, verify that the request really comes from Jira using the secret or signature mechanism offered by the product, and tolerate the same event being delivered twice. The stand-in below routes simplified payloads by event and prints a human message. It does not verify signatures, which a real receiver must.

JS A webhook receiver (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Automation rules can call a web address too, so for simple "tell another system" cases you may not need to write a receiver for Jira at all. Reach for custom API code when the logic is too complex for a rule or when you need to process data in bulk.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What are the three parts of a Jira automation rule?

    A rule starts from a trigger, optionally checks conditions, and then performs actions.
  2. 2. What is {{issue.key}} in an automation message?

    Smart values in double curly braces are placeholders filled in at run time.
  3. 3. How do you move an issue to another status through the REST API?

    Statuses change through transitions, whose ids belong to the workflow, so you list the available ones first.
  4. 4. What is the main advantage of a webhook over polling the API every minute?

    Webhooks send data on demand, while polling repeats requests that mostly find nothing new.
  5. 5. Where should you look first when an automation rule did not behave as expected?

    The audit log records each run and why a rule was skipped or failed.

Summary

  • Automation rules follow when - if - then: a trigger, conditions and actions, with smart values to fill in messages.
  • Design rules to act once, and use the audit log to debug them.
  • The REST API sends JSON over HTTP: create issues, read and search with JQL, and move issues with transition ids; keep API tokens secret and respect rate limits.
  • Webhooks push events from Jira to your URL; answer fast, verify the sender and expect duplicates.
  • The JavaScript examples are stand-ins for the ideas; API calls and payloads here are read-only illustrations to check against the current reference.

Next, see what goes wrong in real teams and how large organizations scale Agile: Common Mistakes and Scaling Agile.