> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira Cloud (Software)

> Client-mode REST API connector for a curated Jira Cloud platform REST v3 slice: create issues from alarms, transitions, and enhanced JQL search

Technical Preview

## Overview

A client-mode connector for a **curated DevOps / OT** slice of the [Jira Cloud platform REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) under `https://YOUR_SITE.atlassian.net`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| (smoke) | `GET /rest/api/3/myself` | Authenticated user |
| (discovery) | `GET /rest/api/3/project` | List projects |
| POST issue (from alarm) | `POST /rest/api/3/issue` | Requires `fields.project`, `fields.issuetype`, `fields.summary` |
| POST issue/\{key}/transitions | `POST /rest/api/3/issue/{issueIdOrKey}/transitions` | Requires `transition.id` |
| GET search?jql= | `GET /rest/api/3/search/jql` | **Enhanced** search — legacy `/rest/api/3/search` is removed (410) |

`BASE_ADDRESS` is `https://{site}.atlassian.net` (no trailing slash; endpoints already include `/rest/api/3/...`). Topics use `devops/jira-cloud/<object>/<verb>`.

> [!NOTE]
>
> Use **`/rest/api/3/search/jql`**, not `/rest/api/3/search`. Request `fields` explicitly (default returns IDs only). Paginate with `nextPageToken`. JQL must be bounded.

> [!NOTE]
>
> Catalog also mentions a server webhook for issue events. This package ships **client events only**. Register Atlassian webhooks via admin UI or Webhooks REST; inbound receive would need a separate `ENABLE_SERVER` connector.

> [!NOTE]
>
> Prefer Hub secrets for tokens and passwords. This template has not been verified against a live Atlassian site. Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Jira Cloud (Software) curated slice
# Auth: Bearer {value.json.access_token} (OAuth 3LO) or Basic email + API token via config
# BASE_ADDRESS: https://YOUR_SITE.atlassian.net

DEFINE ROUTE JiraCloudRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_SITE.atlassian.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getmyself
        WITH SOURCE_TOPIC "devops/jira-cloud/myself/get"
        WITH DESTINATION_TOPIC "devops/jira-cloud/myself/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/api/3/myself"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Listprojects
        WITH SOURCE_TOPIC "devops/jira-cloud/project/list"
        WITH DESTINATION_TOPIC "devops/jira-cloud/project/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/api/3/project"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createissue
        WITH SOURCE_TOPIC "devops/jira-cloud/issue/create"
        WITH DESTINATION_TOPIC "devops/jira-cloud/issue/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/api/3/issue"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Transitionissue
        WITH SOURCE_TOPIC "devops/jira-cloud/issue/transition"
        WITH DESTINATION_TOPIC "devops/jira-cloud/issue/transition/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/api/3/issue/{value.json.issueIdOrKey}/transitions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Searchissuesjql
        WITH SOURCE_TOPIC "devops/jira-cloud/issue/search"
        WITH DESTINATION_TOPIC "devops/jira-cloud/issue/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/api/3/search/jql?jql={value.json.jql}&maxResults={value.json.maxResults}&fields={value.json.fields}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getmyself | GET | `/rest/api/3/myself` | `devops/jira-cloud/myself/get` | `devops/jira-cloud/myself/get/response` |
| Listprojects | GET | `/rest/api/3/project` | `devops/jira-cloud/project/list` | `devops/jira-cloud/project/list/response` |
| Createissue | POST | `/rest/api/3/issue` | `devops/jira-cloud/issue/create` | `devops/jira-cloud/issue/create/response` |
| Transitionissue | POST | `/rest/api/3/issue/{issueIdOrKey}/transitions` | `devops/jira-cloud/issue/transition` | `devops/jira-cloud/issue/transition/response` |
| Searchissuesjql | GET | `/rest/api/3/search/jql?jql=&maxResults=&fields=` | `devops/jira-cloud/issue/search` | `devops/jira-cloud/issue/search/response` |

## Auth

**OAuth 2.0 (3LO) Bearer — default in the template:**

1. Create an OAuth 2.0 (3LO) app in the Atlassian Developer Console with Jira scopes (classic `read:jira-work` / `write:jira-work` or equivalent granular scopes).
2. Obtain an `access_token`.
3. Set connector `BASE_ADDRESS` to `https://{site}.atlassian.net`.
4. Pass `access_token` on the MQTT request payload so headers resolve:
   * `Authorization: Bearer {value.json.access_token}`
5. Store the token in Hub secrets / `GET SECRET`. Never commit real credentials.

**Basic (email + API token):**

1. Create an [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens) for the integration account.
2. Prefer `WITH USERNAME "you@example.com"` and `WITH PASSWORD GET SECRET "ATLASSIAN_API_TOKEN"` on `REST_API_CONFIG` (remove Bearer header lines if using config Basic).

## Example payloads

**Create issue from alarm:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "fields": {
    "project": { "key": "OPS" },
    "issuetype": { "name": "Bug" },
    "summary": "Line sensor fault — Zone A",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            { "type": "text", "text": "Vibration above threshold at 2026-10-04T00:00:00Z" }
          ]
        }
      ]
    }
  }
}
```

**Transition issue:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "issueIdOrKey": "OPS-42",
  "transition": { "id": "31" }
}
```

**Search issues (enhanced JQL):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "jql": "project = OPS AND statusCategory != Done ORDER BY updated DESC",
  "maxResults": "50",
  "fields": "summary,status,assignee,updated"
}
```

## Deploy notes

* Deploy **`JiraCloudRestApi.lot` only** (`-addRoute`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/jira-cloud](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/jira-cloud)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [Jira Service Management](/latest/lot-language/routes/rest-api-apps/jira-service-management)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.