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

# Connect Jira

> Generate an Atlassian API token, enter your credentials in OpenCX, and verify the connection to start creating Jira issues.

export const JiraFlow = () => {
  const BEAM_COLOR = "#22c55e";
  const renderBeam = ({id, d, duration = 2.8, delay = 0, reverse = false}) => {
    const values = reverse ? {
      x1: "110%;-10%",
      x2: "120%;0%"
    } : {
      x1: "-10%;110%",
      x2: "0%;120%"
    };
    return <g key={id}>
        <path d={d} stroke="currentColor" strokeOpacity="0.18" strokeWidth="1.5" fill="none" strokeLinecap="round" />
        <path d={d} stroke={`url(#${id})`} strokeWidth="2" fill="none" strokeLinecap="round" />
        <defs>
          <linearGradient id={id} gradientUnits="userSpaceOnUse" x1="0" y1="0" x2="0" y2="0">
            <stop offset="0%" stopColor={BEAM_COLOR} stopOpacity="0" />
            <stop offset="45%" stopColor={BEAM_COLOR} stopOpacity="1" />
            <stop offset="55%" stopColor={BEAM_COLOR} stopOpacity="1" />
            <stop offset="100%" stopColor={BEAM_COLOR} stopOpacity="0" />
            <animate attributeName="x1" values={values.x1} dur={`${duration}s`} begin={`${delay}s`} repeatCount="indefinite" />
            <animate attributeName="x2" values={values.x2} dur={`${duration}s`} begin={`${delay}s`} repeatCount="indefinite" />
          </linearGradient>
        </defs>
      </g>;
  };
  const SRC_X = 120, OCX_X = 420, JIRA_X = 740;
  const MID = 180, R = 44, SRC_R = 22;
  const sources = [{
    key: "insights",
    label: "Insights",
    y: 90
  }, {
    key: "recommendations",
    label: "Recommendations",
    y: 180
  }, {
    key: "sessions",
    label: "Sessions",
    y: 270
  }];
  const srcBeams = sources.map((s, i) => ({
    id: `jira-src-${i}`,
    d: `M ${SRC_X + SRC_R},${s.y} C ${SRC_X + SRC_R + 80},${s.y} ${OCX_X - R - 80},${MID} ${OCX_X - R},${MID}`,
    delay: i * 0.4
  }));
  const outB = `M ${OCX_X + R},${MID} C ${OCX_X + 120},${MID} ${JIRA_X - R - 120},${MID} ${JIRA_X - R},${MID}`;
  return <div className="zendesk-flow not-prose my-8 w-full">
      <div className="zendesk-flow-frame relative w-full overflow-hidden rounded-md border border-black/10 bg-white px-4 py-6 dark:border-white/10 dark:bg-zinc-950">
        <div className="zendesk-flow-grid pointer-events-none absolute inset-0" aria-hidden />
        <svg viewBox="0 0 860 360" preserveAspectRatio="xMidYMid meet" xmlns="http://www.w3.org/2000/svg" className="relative z-[1] block w-full text-zinc-500 dark:text-zinc-400" role="img" aria-label="Jira flow: OpenCX creates Jira issues from three sources — Insights, Recommendations, and Sessions — unidirectional">
          {srcBeams.map(b => renderBeam({
    id: b.id,
    d: b.d,
    duration: 3.0,
    delay: b.delay
  }))}
          {renderBeam({
    id: "jira-out",
    d: outB,
    duration: 2.4,
    delay: 0.5
  })}

          <text x={(OCX_X + JIRA_X) / 2} y={MID - 18} textAnchor="middle" className="fill-zinc-500 dark:fill-zinc-400" style={{
    font: "500 11px ui-sans-serif, system-ui, sans-serif"
  }}>Create issue</text>

          {}
          {sources.map(s => <g key={s.key}>
              <rect x={SRC_X - 54} y={s.y - 18} width="108" height="36" rx="8" className="fill-white stroke-black/10 dark:fill-zinc-900 dark:stroke-white/10" strokeWidth="1" />
              <g transform={`translate(${SRC_X - 44} ${s.y - 7})`} className="fill-none stroke-zinc-600 dark:stroke-zinc-300" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round">
                {s.key === "insights" && <>
                    <circle cx="7" cy="7" r="5" />
                    <path d="M 7 2 L 7 12 M 2 7 L 12 7" />
                  </>}
                {s.key === "recommendations" && <path d="M 2 7 L 6 11 L 12 2" />}
                {s.key === "sessions" && <>
                    <rect x="1" y="2" width="12" height="10" rx="1.5" />
                    <path d="M 3 5 L 11 5 M 3 8 L 8 8" />
                  </>}
              </g>
              <text x={SRC_X - 28} y={s.y + 4} className="fill-zinc-700 dark:fill-zinc-200" style={{
    font: "500 11.5px ui-sans-serif, system-ui, sans-serif"
  }}>{s.label}</text>
            </g>)}

          <text x={SRC_X} y={40} textAnchor="middle" className="fill-zinc-500 dark:fill-zinc-400" style={{
    font: "500 11px ui-sans-serif, system-ui, sans-serif"
  }}>OpenCX sources</text>

          {}
          <g>
            <circle cx={OCX_X} cy={MID} r={R + 4} className="fill-none" stroke={BEAM_COLOR} strokeOpacity="0.25" strokeWidth="1.5">
              <animate attributeName="r" values={`${R + 2};${R + 12};${R + 2}`} dur="3.6s" repeatCount="indefinite" />
              <animate attributeName="stroke-opacity" values="0.35;0;0.35" dur="3.6s" repeatCount="indefinite" />
            </circle>
            <circle cx={OCX_X} cy={MID} r={R} className="fill-white stroke-black/10 dark:fill-zinc-900 dark:stroke-white/10" strokeWidth="1" />
            <foreignObject x={OCX_X - 34} y={MID - 18} width="68" height="36">
              <div className="flex h-full w-full items-center justify-center">
                <img src="/logo-light.svg" alt="" className="block h-full w-full object-contain dark:hidden" />
                <img src="/logo.svg" alt="" className="hidden h-full w-full object-contain dark:block" />
              </div>
            </foreignObject>
            <text x={OCX_X} y={MID + R + 22} textAnchor="middle" className="fill-zinc-700 dark:fill-zinc-200" style={{
    font: "600 12px ui-sans-serif, system-ui, sans-serif"
  }}>OpenCX</text>
            <text x={OCX_X} y={MID + R + 36} textAnchor="middle" className="fill-zinc-500 dark:fill-zinc-400" style={{
    font: "400 10.5px ui-sans-serif, system-ui, sans-serif"
  }}>workflow · dashboard push</text>
          </g>

          {}
          <g>
            <circle cx={JIRA_X} cy={MID} r={R} className="fill-white stroke-black/10 dark:fill-zinc-900 dark:stroke-white/10" strokeWidth="1" />
            <foreignObject x={JIRA_X - 22} y={MID - 22} width="44" height="44">
              <div className="flex h-full w-full items-center justify-center">
                <img src="/images/integrations/jira.svg" alt="" className="h-8 w-8 object-contain" />
              </div>
            </foreignObject>
            <text x={JIRA_X} y={MID + R + 22} textAnchor="middle" className="fill-zinc-700 dark:fill-zinc-200" style={{
    font: "600 12px ui-sans-serif, system-ui, sans-serif"
  }}>Jira Cloud</text>
            <text x={JIRA_X} y={MID + R + 36} textAnchor="middle" className="fill-zinc-500 dark:fill-zinc-400" style={{
    font: "400 10.5px ui-sans-serif, system-ui, sans-serif"
  }}>Issue (one-way)</text>
            {}
            <g>
              <rect x={JIRA_X + 44} y={MID - 18} width="64" height="36" rx="5" className="fill-white stroke-black/10 dark:fill-zinc-900 dark:stroke-white/10" strokeWidth="1" />
              <rect x={JIRA_X + 48} y={MID - 12} width="14" height="4" rx="1" fill={BEAM_COLOR} />
              <rect x={JIRA_X + 48} y={MID - 4} width="56" height="3" className="fill-zinc-400 dark:fill-zinc-500" />
              <rect x={JIRA_X + 48} y={MID + 2} width="40" height="3" className="fill-zinc-400 dark:fill-zinc-500" />
              <rect x={JIRA_X + 48} y={MID + 8} width="32" height="3" className="fill-zinc-400 dark:fill-zinc-500" />
            </g>
          </g>
        </svg>
      </div>
    </div>;
};

<Warning>
  The Jira integration is in **closed beta**. The setup steps below apply once your organization is enrolled. Contact [support@open.cx](mailto:support@open.cx) for access.
</Warning>

The Jira integration uses an <Tooltip tip="A long-lived credential generated in your Atlassian account settings. Bound to the user whose email you provide.">Atlassian API token</Tooltip> to authenticate with your Jira Cloud instance. OpenCX verifies the credentials before saving — a wrong domain or token returns an error and nothing persists.

<JiraFlow />

<Info>
  Setup takes about 5 minutes. You need admin access in both your Atlassian account and your OpenCX organization.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Jira Cloud account" icon="cloud">
    The integration works with **Jira Cloud only** (the `*.atlassian.net` hosted version). Jira Server and Jira Data Center are not supported.
  </Accordion>

  <Accordion title="Atlassian API token" icon="key">
    You generate this from your [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens). The token is bound to your Atlassian account — if the account is deactivated or loses project access, the integration stops working.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="user-shield">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Generate an Atlassian API token">
    Open [**Atlassian account → Security → API tokens**](https://id.atlassian.com/manage-profile/security/api-tokens) and click **Create API token**.

    1. Label it `OpenCX` (or anything recognizable).
    2. **Copy the token immediately** — Atlassian hides it after you close the dialog.

    <Warning>
      The token inherits the permissions of the Atlassian account that created it. Use an account with access to all Jira projects you want OpenCX to create issues in.
    </Warning>
  </Step>

  <Step title="Open Jira settings in OpenCX">
    In your OpenCX dashboard, go to [**Settings → Integrations**](https://platform.open.cx/settings/integrations) and select **Jira**.
  </Step>

  <Step title="Enter your credentials">
    | Field         | Value                                                                             |
    | ------------- | --------------------------------------------------------------------------------- |
    | **Domain**    | Your Atlassian Cloud domain — e.g. `acme.atlassian.net`. Include the full domain. |
    | **Email**     | The email address of the Atlassian account that owns the API token.               |
    | **API Token** | The token you just copied.                                                        |

    Click **Verify & Save**. OpenCX tests the connection by authenticating against your Jira instance before persisting. A wrong domain, expired token, or incorrect email returns an error.
  </Step>

  <Step title="Select a default project and issue type">
    After verification succeeds, select:

    * **Default project** — the Jira project where issues are created when no override is specified.
    * **Default issue type** — the issue type used by default (e.g. Task, Bug, Story).

    You can override both per issue when pushing recommendations or insights to Jira.
  </Step>

  <Step title="Verify end to end">
    Navigate to [**AI Recommendations**](https://platform.open.cx/reports/voice-of-customer) in your OpenCX dashboard. Pick any recommendation and push it to Jira. Within a few seconds:

    1. A new issue appears in your default Jira project.
    2. The issue description includes the recommendation summary and a link back to the OpenCX session.

    If the issue doesn't appear, check [Troubleshooting](/integrations/jira/troubleshooting).
  </Step>
</Steps>

## Configure field mappings

Map OpenCX data to your Jira custom fields so issues are populated with structured data on creation.

<Steps>
  <Step title="Open field mappings">
    In the Jira integration settings, navigate to the **Field Mappings** section.
  </Step>

  <Step title="Add a mapping">
    For each custom field you want to populate:

    | Setting          | Description                                                      |
    | ---------------- | ---------------------------------------------------------------- |
    | **Jira field**   | The Jira field to populate — select from your available fields.  |
    | **OpenCX field** | The OpenCX data source to map from.                              |
    | **Custom field** | Toggle on if this is a Jira custom field (not a built-in field). |

    Mappings apply to all issues OpenCX creates. Built-in fields like project, issue type, and priority are configured in the main integration settings.
  </Step>
</Steps>

<Tip>
  Start with the fields your team filters and reports on most. You can add more mappings at any time without disrupting existing issues.
</Tip>

## Rotating the API token

Regenerating the Atlassian API token requires updating OpenCX:

1. Create a new token in [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens).
2. Paste it into [Settings → Integrations → Jira](https://platform.open.cx/settings/integrations) and save.
3. Revoke the old token in Atlassian.

## Disconnecting

In your OpenCX dashboard, open the Jira integration settings and click **Disconnect**. Issues already created in Jira remain untouched — disconnecting only stops future issue creation.

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Overview" icon="list-check" href="/integrations/jira/overview">
    What the Jira integration does and how conversations become issues.
  </Card>

  <Card title="Issue Flow" icon="diagram-project" href="/integrations/jira/issue-flow">
    How issues are created from recommendations, insights, and conversations.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/jira/troubleshooting">
    Credentials failing, issues not created, field mappings missing.
  </Card>

  <Card title="Handoff" icon="user-group" href="/handoff/introduction">
    How conversations escalate to human agents and downstream integrations.
  </Card>
</CardGroup>