Jira Cloud

Support and marketing

The Jira Cloud connector reads and writes issues through the Jira Cloud REST API. It reaches sites at yoursite.atlassian.net. Jira Server and Jira Data Center are not supported.

When to use it

• You read issues into a warehouse to join delivery data with other data.
• You raise a Jira issue from a form, a support ticket or a monitoring alert in another system.
• You move issues between projects or out of Jira.

What you need

• Your Jira site name.
• An Atlassian API token, and the email of the Atlassian account it belongs to.

Jira Cloud offers an API token only. Everything the connector does runs as that account. A project the account cannot see is a project the data pipeline cannot see.

Find your site name

Sign in to Jira and look at the address bar. The label between https:// and .atlassian.net is your site name. For https://acme.atlassian.net/jira/software that is acme. Enter the label alone. A value with a dot, a slash, a colon or an at sign is refused.

Set up in Atlassian

1. Go to id.atlassian.com, then Security > API tokens, and create a token. Note which account it belongs to.
2. Note your site name from the Jira address bar.
3. In DataLug, add a Jira Cloud connection.
4. Paste the API token, enter that account's email, and enter the site name.
5. Click Test connection.

Connect

The connection form lists its steps on the left. Open any step from that list. The Environments step holds the values that differ per environment.

Test connection is in the form footer. Beside it, Test against picks Base, the connection as saved, or an environment, whose values are applied first.

Field	Step	What to enter
Auth Type	Authentication	API Token. Jira Cloud offers an API token only.
Email	Authentication	The email of the Atlassian account the token belongs to.
API Token	Authentication	Create one at id.atlassian.com under Security > API tokens.
Site Name	Connection	The label alone, such as acme.

Jira signs every request with the email and the token together. A token from a different account, or the right token with the wrong email, is rejected.

Stored secrets are never sent back to the browser. To change one, use Replace.

Supported operations

Action	Node	Operations
Query (Source)	Source node	Query, with an optional Filter and Limit
Load (Target)	Load node	Insert, Update, Delete

Read and write. Issue, one record per request.

Read only. Issue Comment, Issue Worklog, Project, User, Issue Type, Status, Priority, Resolution, Field and Label.

Not supported: Upsert, Jira Service Management, boards and sprints, change history, attachment downloads, writing worklogs.

Read issues with JQL

Issues are read through Jira's search, which takes JQL in the Filter box. JQL is the language of Jira's own search bar.

Jira refuses an issue search with no restriction, so give the filter a project or another narrowing clause.

Filter	What it reads
project = ACME	Every issue in one project
project = ACME AND updated >= -7d	That project, changed in the last week
assignee = currentUser() AND status != Done	Your open work
created >= "2026-01-01"	Everything raised since that date

The other objects are read directly and take no filter. A filter on one of them stops the run with a message.

Custom fields

A Jira custom field has a machine name, such as customfield_10021, and a display name, such as "Story Points". The column is named after the machine name, and the display name is its label. Renaming the field in Jira changes the label and keeps the column.

Rich text

Jira stores descriptions and comments as Atlassian Document Format. DataLug flattens it to text: lists become semicolon-separated values and other objects become JSON. Formatting is not kept.

Comments and worklogs

A comment or worklog exists only under its issue, so DataLug reads the issues first and then reads each issue's comments or worklogs.

• A Source node reading Issue Comment or Issue Worklog needs a JQL Filter or a Limit.
• Each row carries an issue_id column.
• An issue whose comments cannot be read becomes a row with its id and a dl_error column that says why.
• Preview is not available for these two objects.

Limits

Jira Cloud limits requests with an hourly points budget and per-second burst limits, and answers 429 with a Retry-After header past either. See Atlassian's rate limiting.

The API limits card has no default throttle for Jira Cloud. Page size is at most 100.

The API limits card on the connection form is collapsed by default. Every field on it is optional, and a blank field uses the default shown below it.

Setting	What it does	Default
Requests per period, Period	Paces outgoing calls. Set both to throttle.	No throttle, or the rate shown on the card.
Page size	Rows per request. A larger value is reduced to the provider's maximum.	The maximum shown on the card, or set by the provider.
Max attempts	Tries per call, including the first.	3
Cool-off (ms)	The first wait after a 429. Later waits grow from it.	500 ms
Requests at once	Requests open at the same time within one run.	No limit

A Retry-After header from the provider overrides the cool-off. The pace applies per connection and is shared by every run on it. See Run performance.

DataLug retries a call that the provider refused with 429, and a call that could not connect. A read is also retried after a 408, a 5xx or a dropped connection. A write is retried only after a 429 or a failed connection.

A Retry-After delay of up to one minute is honoured. A longer one fails the call with the 429.

Troubleshooting

What you see	What it means	What to try
400 on an Issue read with no filter, or mentioning an unbounded query	Jira refuses an issue search with no restriction.	Put a JQL query in the Filter box, such as project = ACME.
400 mentioning JQL	The query has a syntax error, or names a field that does not exist.	Run the same query in Jira's issue search to see its error.
401 on test or on a run	The token is wrong, or the email does not match its account.	Check both at id.atlassian.com > Security > API tokens.
The test passes but a project returns nothing	The token's account cannot see that project.	Grant that account Browse permission on the project in Jira.
A column called customfield_10021	The field's machine name.	Read its label.
A description arrives as [object Object]	The value was not flattened.	The account Owner emails DataLug support at support@datalug.io with the object and field.
A run on comments or worklogs asks for a filter or a row limit	They are read one issue at a time.	Set a JQL Filter, a Limit, or both.
Some comment rows carry dl_error	Those issues could not be read.	Read the message. It is usually a project permission.
429 Too Many Requests	Past the site's rate limit.	The run backs off and retries. If it recurs, set Requests per period.

Related

• Source node and Load node.
• Connections for environments and sharing.
• Zendesk Support.