Jira

Sync data from your warehouse to Jira Cloud. Zeotap creates and updates issues in your Jira projects, keeping your issue tracker enriched with the latest customer and operational data.

Prerequisites

• A Jira Cloud account (Jira Server and Data Center are not supported)
• Your Jira site URL (e.g., https://mycompany.atlassian.net)
• A Jira project key (e.g., PROJ)
• An Atlassian email address and API token for authentication

Permissions

The authenticating user must have:

• Browse Projects permission on the target project
• Create Issues permission to create new issues
• Edit Issues permission to update existing issues
• Assign Issues permission if mapping the assignee field

Authentication

Jira uses Basic authentication with an Atlassian email and API token.

Generating an API Token

1. Go to Atlassian API Tokens
2. Click Create API token
3. Enter a descriptive label (e.g., “Zeotap Integration”)
4. Copy the generated token — it is only shown once

Configuring in Zeotap

1. Navigate to Destinations in the left sidebar
2. Click Add Destination and select Jira
3. Enter your Atlassian Email (the email for your Atlassian account)
4. Paste the API Token you generated above
5. Click Test Connection to verify

Configuration

Target Settings

Supported Operations

Sync Modes

• Insert: Creates new issues for every row in the sync.
• Update: Updates existing issues. Each row must include an issue_key field (e.g., PROJ-123) to identify the issue.
• Upsert: Rows with an issue_key are updated; rows without are created as new issues.

Audience Sync Modes

Jira does not support audience sync modes. Issues are not membership-based entities.

Features

• Field Mapping: Yes — map warehouse columns to Jira issue fields
• Schema Introspection: No — use the default fields list or enter custom field IDs manually

Required Mapping Fields

Default Destination Fields

For custom fields, map to the Jira custom field ID (e.g., customfield_10001). Custom field values are passed through to the API as-is.

How It Works

1. Create operations use the Jira bulk issue creation endpoint (POST /rest/api/3/issue/bulk), which supports up to 50 issues per request. Rows are automatically chunked into batches of 50.

2. Update operations use individual PUT /rest/api/3/issue/{issueKey} calls because Jira does not provide a bulk update endpoint. Each row is updated sequentially.

3. Upsert operations split rows into creates and updates based on whether the issue_key field is present. Creates are batched; updates are sent individually.

4. Description fields are automatically converted from plain text to Jira’s Atlassian Document Format (ADF), which is required by the v3 API.

5. Structured fields like priority, assignee, reporter, labels, and components are automatically mapped from simple values (strings) to the nested object format that the Jira API expects.

Rate Limits

Jira Cloud enforces multiple rate limiting systems:

• Points-based quota: Each API call consumes points based on complexity. Creating 50 issues in a bulk request consumes approximately 50 points. The per-hour quota varies by plan.
• Per-second rate limits: Limits on requests per second per endpoint.
• Concurrent request limit: A maximum of 5 concurrent requests across all users for bulk operations.

Zeotap handles rate limiting automatically with exponential backoff and retry. If you encounter persistent rate limit errors, reduce the sync frequency or contact your Jira Cloud administrator to review your plan’s API limits.

Best Practices

• Use upsert mode when you want to keep issues in sync — include issue_key for rows that already have corresponding Jira issues.
• Map issue_key in your model to enable updates. Without it, upsert mode treats every row as a new issue.
• Use account IDs for assignee and reporter fields, not email addresses. You can find account IDs via the Jira user picker API.
• Keep descriptions concise — very long descriptions are converted to a single ADF paragraph. For rich formatting, consider using the Jira API’s full ADF structure via a custom field.
• Test with a staging project before syncing to production projects to verify field mappings.

Troubleshooting

Authentication failed: invalid email or API token

Verify that you are using the email address associated with your Atlassian account (not a Jira display name) and that the API token is correct. API tokens are different from passwords. Generate a new token at Atlassian API Tokens.

Project not found

Check that the project key matches exactly (project keys are case-sensitive). Verify the authenticating user has the Browse Projects permission on the target project.

Issue creation fails with field validation errors

Ensure all required fields for the issue type are mapped. Some Jira projects have custom required fields configured via field configuration schemes. Check your project’s field configuration in Jira Settings > Issues > Field Configurations.

Assignee or reporter field rejected

Jira Cloud requires account IDs (e.g., 5b10ac8d82e05b22cc7d4ef5), not email addresses, for user fields. Use the Jira user search API to look up account IDs.

Labels not applying

Labels must not contain spaces. If your source data contains spaces in labels, transform them before syncing (e.g., replace spaces with hyphens).

Rate limit errors

If you see HTTP 429 errors, Zeotap retries automatically with backoff. Persistent failures indicate your Jira plan’s API quota is exhausted. Reduce sync frequency or upgrade your Jira Cloud plan.

Description appears as plain text

The Jira v3 API requires descriptions in Atlassian Document Format (ADF). Zeotap automatically wraps plain text in ADF. If you need rich formatting (headings, lists, links), you must provide the full ADF JSON structure in your source data.

Custom field values not applying

Custom fields must be referenced by their field ID (e.g., customfield_10001), not their display name. Find custom field IDs in Jira Settings > Issues > Custom Fields or via the Jira REST API (/rest/api/3/field).