> ## Documentation Index > Fetch the complete documentation index at: https://docs.nekt.com/llms.txt > Use this file to discover all available pages before exploring further. # Jira as a data source > Bring data from Jira to Nekt. Jira is Atlassian's project management and issue tracking platform designed for software development teams. It provides tools for agile project management, bug tracking, and workflow automation to help teams plan, track, and release software efficiently. Jira ## Configuring Jira as a Source In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the **Jira** option from the list of connectors. Click **Next** and you'll be prompted to add your access. ### 1. Add account access Use your Jira Cloud credentials and workspace information. If needed, check Jira's [REST API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#version). The following configurations are available: * **API token**: The token used to authenticate against Jira. For instructions on generating it, check [Atlassian's guide](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/). * **User email**: The email address associated with the API token. * **Workspace domain**: Your Jira domain, without `https://` (for example, `company.atlassian.net`). * **Start date**: Optional. The earliest timestamp used for incremental extraction. If left empty, all available history will be fetched. * **Project keys**: Optional list of project keys to scope extraction. When defined, project-dependent streams are filtered to those projects. * **Issues stream JQL query**: Optional custom JQL filter for the `issues` stream. It is combined with the start date filter and project filter. Once you're done, click **Next**. ### 2. Select streams Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. > Tip: The stream can be found more easily by typing its name. Select the streams and click **Next**. ### 3. Configure data streams Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync. * **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully. * **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source. * **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster! * **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE. * Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched. * Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog. Once you are done configuring, click **Next**. ### 4. Configure data source Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings: * Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control). * Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while. When you are ready, click **Next** to finalize the setup. ### 5. Check your new source You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog. For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run. # Streams and Fields Below you'll find all available data streams from Jira and their corresponding key fields. Base project entities used by other project-scoped streams. **Primary key:** * `id` **Key Fields:** | Field | Type | Description | | :-------------------------- | :------ | :---------------------------------- | | `key` | String | Project key used as Jira identifier | | `name` | String | Project name | | `project_type_key` | String | Project type | | `is_private` | Boolean | Project visibility flag | | `project_category` | Object | Project category metadata | | `insight.total_issue_count` | Integer | Total number of issues | Agile boards associated with projects. **Primary key:** * `id` **Parent stream:** * `projects` (filtered by project context) **Key Fields:** | Field | Type | Description | | :---------------------- | :----- | :----------------------------------- | | `name` | String | Board name | | `type` | String | Board type (`scrum`, `kanban`, etc.) | | `location.project_id` | String | Related project ID | | `location.project_key` | String | Related project key | | `location.project_name` | String | Related project name | Sprint entities collected from agile boards. **Replication key:** * `id` **Parent stream:** * `boards` (only boards with type `scrum`) **Key Fields:** | Field | Type | Description | | :-------------- | :----- | :---------------- | | `state` | String | Sprint state | | `name` | String | Sprint name | | `start_date` | String | Sprint start date | | `end_date` | String | Sprint end date | | `complete_date` | String | Completion date | | `board_id` | String | Parent board ID | | `goal` | String | Sprint goal | Issue type definitions available per project. **Primary key:** * `id` **Parent stream:** * `projects` (filtered by project context) **Key Fields:** | Field | Type | Description | | :------------------ | :------ | :------------------------------ | | `name` | String | Issue type name | | `description` | String | Issue type description | | `subtask` | Boolean | Whether the type is a subtask | | `hierarchy_level` | Integer | Hierarchy level in Jira | | `scope.project.id` | String | Project-scoped type project ID | | `scope.project.key` | String | Project-scoped type project key | Field definitions and metadata available for projects. **Primary key:** * `id` **Parent stream:** * `projects` (filtered by project context) **Key Fields:** | Field | Type | Description | | :-------------- | :------ | :---------------------------------------- | | `key` | String | Field key | | `name` | String | Field name | | `custom` | Boolean | Whether the field is custom | | `orderable` | Boolean | Whether the field can be used in ordering | | `searchable` | Boolean | Whether the field can be searched | | `schema.type` | String | Data type for field values | | `schema.custom` | String | Custom schema identifier | Jira users available to the authenticated account. **Primary key:** * `account_id` **Key Fields:** | Field | Type | Description | | :-------------- | :------ | :------------------------- | | `display_name` | String | User display name | | `email_address` | String | User email | | `account_type` | String | Account type | | `active` | Boolean | Whether the user is active | | `time_zone` | String | User time zone | | `locale` | String | User locale | Main issue entities from Jira. The `fields` property is serialized as a single JSON string, containing all standard and custom issue fields. **Primary key:** * `id` **Replication key:** * `updated` **Key Fields:** | Field | Type | Description | | :------- | :----- | :---------------------------------------------------------------------------------------------------- | | `id` | String | Unique identifier of the record | | `key` | String | Issue key | | `self` | String | URL of the resource | | `fields` | String | Full set of issue properties as a JSON string (contains summary, status, assignee, and custom fields) | Change history for each issue. **Primary key:** * `id` **Replication key:** * `created` **Parent stream:** * `issues` **Key Fields:** | Field | Type | Description | | :------------------ | :----- | :--------------------------- | | `issue_id` | String | Parent issue ID | | `author.account_id` | String | Author account ID | | `created` | String | Changelog creation timestamp | | `items.field` | String | Changed field | | `items.from` | String | Previous value ID | | `items.to` | String | New value ID | | `items.from_string` | String | Previous value (display) | | `items.to_string` | String | New value (display) | # Data Model The following diagram shows the relationship between the main Jira streams. Note that links originating from `Issues` require extracting values from the `fields` JSON string. ```mermaid theme={null} graph TD; Projects("Projects"); Boards("Boards"); Sprints("Sprints"); IssueTypes("Issue Types"); Fields("Fields"); Issues("Issues"); IssueChangelog("Issue Changelog"); Users("Users"); Boards -- "project_key" --> Projects; Sprints -- "board_id" --> Boards; IssueTypes -- "project_id" --> Projects; Fields -- "project_id" --> Projects; Issues -- "fields -> project.id" --> Projects; Issues -- "fields -> assignee.account_id" --> Users; Issues -- "fields -> reporter.account_id" --> Users; IssueChangelog -- "issue_id" --> Issues; ``` # Transformation example: extracting fields from JSON The `fields` column in the `issues` stream stores all standard and custom attributes as a single JSON string. To analyze dimensions like summary, status, project, or assignee in [Explorer](https://app.nekt.ai/explorer) or downstream models, parse the JSON and expose the keys as separate columns. ```sql theme={null} SELECT id, key, json_extract_scalar(fields, '$.summary') AS summary, json_extract_scalar(fields, '$.status.name') AS status_name, json_extract_scalar(fields, '$.project.key') AS project_key, json_extract_scalar(fields, '$.assignee.account_id') AS assignee_account_id, json_extract_scalar(fields, '$.issuetype.name') AS issue_type, CAST(json_extract_scalar(fields, '$.created') AS TIMESTAMP) AS created_at, CAST(json_extract_scalar(fields, '$.updated') AS TIMESTAMP) AS updated_at FROM nekt_raw.jira_issues ``` ```sql theme={null} SELECT id, key, JSON_VALUE(fields, '$.summary') AS summary, JSON_VALUE(fields, '$.status.name') AS status_name, JSON_VALUE(fields, '$.project.key') AS project_key, JSON_VALUE(fields, '$.assignee.account_id') AS assignee_account_id, JSON_VALUE(fields, '$.issuetype.name') AS issue_type, CAST(JSON_VALUE(fields, '$.created') AS TIMESTAMP) AS created_at, CAST(JSON_VALUE(fields, '$.updated') AS TIMESTAMP) AS updated_at FROM `nekt_raw.jira_issues` ``` You can run this as an ad-hoc query in Explorer or turn it into a [transformation](https://docs.nekt.com/get-started/core-concepts/transformations) that writes to a new table so you have a flattened view of Jira issues for reporting and joins. ## Implementation Notes ### Filtering behavior * `project_keys` limits project-scoped extraction to specific Jira projects. * `issues` applies an `updated >= start_date` filter if a starting timestamp is available, and can additionally apply a custom JQL query. * The final JQL for `issues` combines the start date (if present), optional project keys, and optional custom JQL with logical `and`. * The Jira `/search/jql` API endpoint rejects queries that are entirely unbounded. To safely capture all historical records during a full table extraction or the initial run of an incremental extraction (before a state or bookmark is set), the connector automatically falls back to a minimal date bound (`updated >= '1900/01/01 00:00'`). This ensures all issues are properly synced while keeping the request bounded as required by Jira's servers. ### Stream hierarchy behavior * `boards`, `fields`, and `issue_types` are project-scoped child streams. * `sprints` is collected only from `scrum` boards. * `issue_changelog` is collected per issue and includes `issue_id` as parent context. ## Skills for agents Jira connector documentation as plain markdown, for use in AI agent contexts.