Docs/Connectors

Jira

Jira Cloud issues as records, and each issue's changelog and comments as episodes.

The jira connector reads Jira Cloud issues and their history.

Connector name jira
Products Records, episodes
Credentials An Atlassian account email and API token, or an OAuth access token
Permissions Browse projects on every project you pull

What it pulls

Records. One issue record per issue updated in the window: ID, project key, issue type, summary, description as plain text, status and status category, priority, resolution, assignee, reporter, labels, components, parent ID, created, updated, resolved and due dates, original estimate and time spent in seconds.

Episodes. For each issue, its creation (type and project), every changelog entry (field, old value, new value, time, author), and every comment with its author and time. Mentions in descriptions and comments become [MENTION] before scrubbing.

Assignee and reporter names become tokens. Summaries, descriptions and comments are free text and are redacted.

Credentials

  1. Sign in to Atlassian as an account that can browse the projects you want to share. A dedicated read-only account is best.
  2. Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens.
  3. Give the SDK your site (acme.atlassian.net), the account email and the apiToken.

To use an OAuth access token instead, set accessToken and set site to https://api.atlassian.com/ex/jira/<cloudId>.

Connect

bash
datayield connect jira -o site=acme.atlassian.net -o email=ops@acme.example \
  -o apiToken=env:JIRA_TOKEN -o jql='project in (ENG, OPS)'

Secret options passed directly are saved to ~/.datayield/credentials. Values written as env:NAME are read from the environment at run time, which suits CI. See CLI reference.

Options

Option Required Meaning
site yes acme.atlassian.net, or a full https:// base URL
email with apiToken The account that owns the token
apiToken with email Stored as a secret
accessToken instead of the above An OAuth token. Stored as a secret.
jql no Extra JQL to narrow the issues, such as project in (ENG, OPS)

Use jql to keep projects out of the dataset, such as HR or security projects.

New records on each run

Issues are searched with JQL for an updated time between the last successful run and now, oldest first. Jira reads those times in the token owner's time zone. An issue updated again later is sent again, and its episode is rebuilt from the full changelog.