Skip to main content

​
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

1

Create an API token

Create an Atlassian API token for a dedicated service account with access only to the required projects.
2

Store the credential

In Settings → Integrations, select Add integration, choose Jira, and enter the Jira host, service-account email, and API token.
3

Create and test a connection

Bind the credential to the Jira host and verify the connection before using it in a workflow.
4

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.

​
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:
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.