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

# Jira

> Configure governed Jira issue automation and authenticated synchronization.

## Overview

The Jira connector supports Jira Software and Jira Service Management project
discovery, issue creation, updates, comments, transitions, issue linking, and
authenticated inbound synchronization. Connection authentication is stored in
the credential vault and is never returned from management APIs.

## Configure

<Steps>
  <Step title="Create an API token">
    Create an Atlassian API token for a dedicated service account with access
    only to the required projects.
  </Step>

  <Step title="Store the credential">
    In **Settings → Integrations**, select **Add integration**, choose **Jira**, and enter the Jira host,
    service-account email, and API token.
  </Step>

  <Step title="Create and test a connection">
    Bind the credential to the Jira host and verify the connection before using
    it in a workflow.
  </Step>

  <Step title="Publish the Jira policy">
    In the connection's **Automation** and **Advanced** tabs, configure the
    synchronization direction, conflict behavior, default project and issue
    type, and any explicit mappings. Saving a changed policy increments its
    version. Durable outbound events retain the policy version and snapshot that
    created them.
  </Step>
</Steps>

## Governance and mappings

The four automation controls are independent:

* **Create issues automatically** handles case creation and alert promotion.
* **Synchronize task creation** creates and links one Jira issue for a new task.
* **Synchronize case updates** sends linked case changes to Jira.
* **Synchronize case closure** sends closure details and uses a configured
  transition when one matches.

Choose **Outbound only**, **Inbound only**, or **Bidirectional**. Inbound-only
policy cannot be saved while outbound automation is enabled. Conflict policy is
evaluated against the remote update time and the most recent local/outbound
change:

* **Newest update wins** applies only the newer change.
* **CaseBender wins** retains local state when Jira is not newer.
* **Jira wins** applies authenticated Jira changes.
* **Manual resolution** suppresses conflicting inbound changes for operator
  review.

Mappings are JSON objects. Keys are matched case-insensitively. Project and
issue-type mappings can use a CaseBender case type, source, or event type such
as `TaskCreated`; the default project and issue type are used when no mapping
matches. Status mappings use Jira transition IDs for outbound changes. Priority
mappings use CaseBender severities `1` through `4`. Assignee mappings map a
CaseBender user ID or email to a Jira account ID. Custom-field mappings map a
CaseBender custom-field name to a Jira `customfield_...` identifier.

The **Unmapped values** policy either leaves the target field unchanged
(`ignore`) or fails the operation for operator review (`error`).

## Configure the inbound webhook

Use the ingestion service URL ending in `/v1/sources/jira` (or the equivalent
path exposed by your reverse proxy). Every Jira webhook request must include:

```text theme={null}
x-casebender-connection-id: <numeric connection ID>
x-casebender-webhook-secret: <one-time connection webhook secret>
```

`Authorization: Bearer <secret>` may replace
`x-casebender-webhook-secret`. If supplied,
`x-casebender-organization-id` must match the connection's owning organization.
Configure issue create, update, delete, transition, assignment, priority, and
comment events according to the inbound fields you enabled.

CaseBender stores a hash of the webhook secret, not the raw value. Rotation
accepts the current and immediately previous hash so operators can update Jira
without an outage. Rotate again only after Jira is using the new secret.

Webhook receipts store identifiers, hashes, state, and sanitized errors; raw
webhook payloads and secrets are not retained. Duplicate delivery identifiers
or payload hashes are acknowledged without applying the change twice.

## Outbound automation reliability

Outbound operations use a tenant-scoped durable outbox. Attempts, policy
snapshot, correlation ID, remote status code, and a path-only request summary
are retained. Response bodies, authorization headers, credentials, and webhook
payloads are not written to operations or audit records.

Retries use exponential backoff. Events that exhaust their attempt budget move
to **DEAD\_LETTER**. From **Settings → Integrations → Health**, an integration
administrator can retry a failed event immediately or replay a dead-letter
event with additional attempts. Recovery reuses the original immutable payload
and idempotency key.

Inbound processing uses an ownership lease. A queue retry may reclaim
`PROCESSING` only after the lease expires. The Health view can release an
expired lease, but it does not recreate the Jira payload; the existing queue
retry or Jira redelivery must still provide it.

## Troubleshooting

1. Test the connection and verify the dedicated service account can browse the
   selected project and perform each enabled action.
2. Confirm the connection is enabled, organization-scoped, and has a live
   credential.
3. Verify the Jira webhook sends the connection ID and current secret to the
   ingestion endpoint.
4. Review the policy version, sync direction, conflict policy, unmapped policy,
   and recent failures in the Health view.
5. Correct invalid project keys, issue types, transition IDs, priorities,
   account IDs, or custom-field IDs before retrying outbound work.
6. For a failed inbound receipt, rely on the worker queue retry or redeliver the
   event from Jira. CaseBender cannot reconstruct a webhook because raw payloads
   are intentionally not stored.

## Rollback

To stop new side effects, disable the connection or turn off the affected
automation controls. To roll back a policy, restore the previous non-secret
mapping values and save; this publishes a new version rather than rewriting
historical outbox snapshots. Existing dead-letter events keep their original
policy and should be replayed only after confirming that policy is still safe.