Set up the Atlassian Jira Cloud (Core) flow¶

This topic describes the steps to install and configure the Atlassian Jira Cloud (Core) flow, the core flow of the Openflow Connector for Jira Cloud. The agile flow is documented separately in Set up the Atlassian Jira Cloud (Agile) flow.

Prerequisites¶

Get the credentials¶

As a Jira Cloud administrator, perform the following tasks in your Atlassian account:

1. Navigate to the API tokens page.
2. Select Create API token with scopes.
3. In the Create an API token dialog box, provide a descriptive name for the API token and select an expiration date for the API token. This can range from 1 to 365 days.
4. Select the API token app Jira.
5. Select the required scopes based on the features you plan to use. See Required API scopes for details.
6. Select Create token.
7. In the Copy your API token dialog box, select Copy to copy your generated API token and then paste the token to the connector parameters, or save it securely.
8. Select Close to close the dialog box.

Required API scopes¶

Atlassian API tokens with scopes list both classic (broader, recommended) and granular (narrower) scopes. Classic scopes are the recommended starting set. Use granular scopes when your organization requires a narrower token; a granular token needs every scope Atlassian lists for an endpoint, not just one.

The core flow always requires these classic baseline scopes (or the equivalent granular set for each table you enable):

• read:jira-work
• read:jira-user (covers users and user groups, and the connection verification and timezone lookup that run at startup against GET /rest/api/3/myself)

The API token owner additionally needs the Browse projects Jira permission on every project that you want to ingest.

For the Enabled Tables parameter that turns optional tables on, see Enabled tables configuration.

The following table lists each destination table, the recommended classic scope, the full set of granular scopes Atlassian documents for the endpoints, and links to the endpoints the connector calls:

For the ISSUE, CHANGELOG, COMMENT, ISSUE_REMOTE_LINK, ISSUE_VOTE, and ISSUE_WATCHER tables, the API token owner must also have permission to view an issue when issue-level security is configured for the issue.

Comments restricted to specific roles or groups are visible only when the API token owner is a member of these roles or groups, regardless of the token scope or permission configuration.

The ISSUE_REMOTE_LINK table requires issue linking to be active in Jira. The ISSUE_VOTE and ISSUE_WATCHER tables require the Jira settings that allow users to vote on and watch issues, respectively.

Tokens without scopes are also supported and grant access based solely on the API token owner’s permissions. However, tokens with scopes are recommended for fine-grained access control.

Set up Snowflake account¶

Set up the connector¶

The core flow is shipped as the Atlassian Jira Cloud (Core) process group. As a data engineer, perform the following tasks to install and configure it.

Install the connector¶

After import, the core flow appears on the canvas as the Atlassian Jira Cloud (Core) process group.

Configure the connector¶

1. Right-click on the imported Atlassian Jira Cloud (Core) process group and select Parameters.
2. Populate the required parameter values as described in Flow parameters.

Flow parameters¶

The core flow uses the following parameter contexts:

• Jira Cloud (Core) Source Parameters: Used to establish connection with the Jira API.
• Jira Cloud (Core) Destination Parameters: Used to establish connection with Snowflake.
• Jira Cloud (Core) Ingestion Parameters: Used to define the configuration of data ingested from Jira.

Jira Cloud (Core) Source Parameters¶

Jira Cloud (Core) Destination Parameters¶

Jira Cloud (Core) Ingestion Parameters¶

Run the flow¶

1. Right-click on the canvas and select Enable all Controller Services.
2. Right-click on the Atlassian Jira Cloud (Core) process group and select Start. The flow starts the data ingestion.

On first run, the flow creates the required Snowflake tables in the destination schema. See Destination tables for the full list of tables created by the core flow and the parameters that control which optional tables are populated.

Resetting the connector state¶

If you need to change the project filter or want to restart the ingestion from scratch, you must clear the ingestion state. The core flow uses a centralized state service rather than per-processor state.

To reset the state, perform the following steps:

1. Right-click the Atlassian Jira Cloud (Core) process group and select Stop.
2. Navigate to the Controller Settings for the process group.
3. Find the StandardJiraIngestionStateService controller service and select View State.
4. Select Clear State. This clears all project tracking, pagination, and timestamp state.
5. Optionally, update the connector parameters if needed.
6. Right-click the Atlassian Jira Cloud (Core) process group and select Start.

Accessing the data¶

Data fetched from Jira is available in the destination tables with explicit column schemas. There is no need to use JSON flattening or views to query the data.

Each entity is stored in its own table. For example, to query issues and their comments:

SELECT i.KEY, i.SUMMARY, c.BODY AS comment_body, c.CREATED AS comment_created
FROM ISSUE i
JOIN COMMENT c ON i.ID = c.ISSUE_ID
ORDER BY c.CREATED DESC;

The ISSUE table stores Jira IDs for issue type, priority, resolution, and status, not the display names. Enable the matching lookup tables (they’re in the default Enabled Tables value) and join them to resolve names:

SELECT
  i.KEY,
  i.SUMMARY,
  it.NAME AS issue_type_name,
  p.NAME AS priority_name,
  r.NAME AS resolution_name,
  s.NAME AS status_name
FROM ISSUE i
LEFT JOIN ISSUE_TYPE it ON i.ISSUE_TYPE = it.ID
LEFT JOIN PRIORITY p ON i.PRIORITY = p.ID
LEFT JOIN RESOLUTION r ON i.RESOLUTION = r.ID
LEFT JOIN STATUS s ON i.STATUS = s.ID
WHERE i._SNOWFLAKE_DELETED = FALSE;

To exclude deleted issues from query results, filter on the connector-managed _SNOWFLAKE_DELETED column. The connector sets this flag to TRUE on the matching ISSUE row when an issue is deleted in Jira, so no anti-join against DELETED_ISSUE is needed:

SELECT i.*
FROM ISSUE i
WHERE i._SNOWFLAKE_DELETED = FALSE;

The DELETED_ISSUE table is still useful when you need the deletion timestamp or the user who performed the deletion. See Connector-managed columns for the full set of connector-managed metadata columns.

Enabled tables configuration¶

The Enabled Tables parameter controls which optional tables are populated. Ingestion of the ISSUE, PROJECT, USER, and FIELD tables is always enabled and can’t be disabled. ISSUE_TYPE, PRIORITY, RESOLUTION, and STATUS are lookup tables that resolve the Jira IDs stored on ISSUE to their descriptive names. Enabling all tables may cause performance issues and require a larger runtime.

Available values for Enabled Tables:

• CHANGELOG (field change history for issues)
• COMMENT (comments on issues)
• ISSUE_REMOTE_LINK (remote links attached to issues)
• ISSUE_SECURITY_SCHEME (issue-level security configurations)
• ISSUE_TYPE (issue type names referenced by issues)
• ISSUE_VOTE (users who voted on issues)
• ISSUE_WATCHER (users watching issues)
• PERMISSION (global and project permission definitions)
• PRIORITY (priority names referenced by issues)
• PROJECT_COMPONENT (components defined in a project)
• PROJECT_VERSION (release versions of a project)
• RESOLUTION (resolution names referenced by issues)
• STATUS (status names and categories referenced by issues)
• USER_GROUP (group memberships per user)
• WORKLOG (time tracking entries on issues)

The per-issue tables (CHANGELOG, COMMENT, ISSUE_REMOTE_LINK, ISSUE_VOTE, ISSUE_WATCHER, WORKLOG) and per-project tables (PROJECT_COMPONENT, PROJECT_VERSION) only ingest data for issues and projects that are also covered by Project Keys Filter.

Some tables are populated by calling the Jira API once per parent entity (for example, once per user or once per issue). On large Jira instances, enabling these tables can significantly increase the number of API calls and the load on the ingestion runtime, and can slow down population of the parent table due to back-pressure on the upstream processor. Enable these tables only when the corresponding data is required.

Issue fields configuration¶

The ISSUE table schema depends on the Issue Fields parameter. The parameter accepts a comma-separated list of field IDs or one of the special values below. Prefix a field with a minus (-) to exclude it. For example, *all,-description returns all fields except description.

• *standard (default): Fetches all non-custom Jira fields. For information about resolving Jira IDs to display names, see Accessing the data.
• *navigable: Fetches all navigable fields.
• *all: Fetches all fields, including custom fields.
• Individual field IDs can be specified (for example, summary,status,customfield_10001).

The default value *standard doesn’t include custom fields. To ingest custom fields, set this parameter to *all or list the custom fields explicitly by ID, for example, *standard,customfield_10001. To find custom field IDs, follow this guide.

Column names in the ISSUE table are derived from Jira field display names by:

1. Uppercasing the display name.
2. Replacing spaces with underscores.
3. Removing every character that isn’t a letter, digit, or underscore.

For example, the display name OF Test (Multi-User) becomes the column OF_TEST_MULTIUSER.

If two fields produce the same column name after this transformation, the second field’s column is suffixed with __<flattened_field_id> to keep names unique. For example, two fields with display name Custom Field and IDs customfield_1 and customfield_2 produce columns CUSTOM_FIELD and CUSTOM_FIELD__CUSTOMFIELD_2.

Jira field types are mapped to Snowflake column types as follows:

Next steps¶

• Set up the Atlassian Jira Cloud (Agile) flow to install the agile flow.
• Migrate from the legacy Openflow Connector for Jira Cloud if you’re moving from a previous version of the Jira Cloud connector.