Jira Connector
Ingest Jira issues, comments, and attachments into CortexDB.
Polls Jira issues (via JQL on updated), their comments, and attachments, and writes them to CortexDB
as experiences.
Two ways to run this connector
Self-hosted — pip install 'cortexdb-connectors[jira]' then cortexdb-sync sync jira. Managed
— CortexDB runs the connector as a worker. See the Connectors overview.
1. Prepare credentials
Create an API token at id.atlassian.com/manage-profile/security/api-tokens. You need three values:
your Jira site URL (e.g. https://acme.atlassian.net), the account email, and the API token. The
connector authenticates as HTTP Basic (email:token).
What gets written
| Event | Modality |
|---|---|
| Issue | document (summary + description, with comments appended as Comments (N): ...) |
| Attachment | uploaded to /v1/blobs, ingested as content.kind="blob_ref" |
Each carries an entity reference to the issue and metadata (issue_key, status, a source_url).
Record keys and comments
- The
idempotency_keyisjira:{issue_key}:{updated-ISO-timestamp}(a comment edit bumps the issue'supdated, so the timestamp is the version marker) — no<project>-prefix segment and nochangelog_id. Attachments key onjira:att:{att_id}. - There are no separate comment or status-change events: comments are included in the issue's
documentcontent, and a new comment bumpsupdated, producing a new version of the issue event.
The key on the wire is derived
The key format above is this connector's internal record identity: it decides which source record an
event belongs to. The idempotency_key actually sent to CortexDB is a derived cxsrc:<56 hex> value
that also hashes the content, labels, observed time and actor, so an unchanged redelivery converges on
the same event while any edit lands as a new one, even where the key format itself is not
content-versioned. Every event also carries a source descriptor with the record's fingerprint. See
Source identity and keys.
Run it yourself
pip install 'cortexdb-connectors[jira]'
pip install cortexdb-cli && cortexdb init
export JIRA_URL=https://acme.atlassian.net # required
export JIRA_EMAIL=you@acme.com # required
export JIRA_API_TOKEN=... # required
export JIRA_PROJECT_KEYS=ENG,PROD # required — the connector aborts with no projects
cortexdb-sync --api-url http://localhost:3141 sync jira
cortexdb-sync --api-url http://localhost:3141 watch jira --interval 300JIRA_PROJECT_KEYS is functionally required
cortexdb-sync list shows only the three auth vars as "required env", but the connector aborts
without projects — supply them via JIRA_PROJECT_KEYS (or a project_keys: [...] list in a
--config YAML, which needs PyYAML: pip install pyyaml or the [all] extra; without it the file is
ignored and the connector aborts). Cursor state persists in ~/.cortexdb/sync_state.json.
Optional settings
Set these as environment variables (or the matching keys in the cortexdb-sync YAML config). Lists are comma-separated. For on/off settings, 1, true, yes or on turns the setting on and any other value turns it off.
| Setting | What it does | Default |
|---|---|---|
JIRA_RECONCILE_DELETIONS | Periodically check for issues deleted in Jira since they were synced | On |
JIRA_RECONCILE_INTERVAL_SECONDS | How often that check runs | 3600 |
JIRA_LEDGER_PATH | File that records synced issues for the deletion check | ~/.cortexdb/jira_ledger.json |