Best Practices

Recommended setup

Start with a simple JQL query

Before building complex queries, test with `project = "YOUR_PROJECT"` or `assignee = currentUser()` to understand the data. Once the data flow runs successfully, refine your query to add filters like status, date ranges, or custom fields.

Use "Detailed data" for analysis

If you're joining Jira data with other sources or building advanced reports, choose the "Detailed data" export format to preserve IDs and metadata. This makes it easier to join issues with other datasets later.

Select only the columns you need

If your Jira instance has many custom fields, explicitly list the columns you need in the "Columns" field. This reduces export size, speeds up the data flow, and makes your destination cleaner and easier to read.

Data refresh and scheduling

Schedule daily refreshes for active projects

If your team moves issues frequently, schedule daily refreshes to keep your reporting sheets up to date. For slower-moving projects, weekly refreshes are usually sufficient.

Use date ranges in JQL to limit historical data

Instead of pulling all issues from the beginning of time, filter by creation date (e.g., `created >= -90d`) to keep exports manageable and faster. Archive old data separately if needed for historical analysis.

Performance optimization

Filter by project or sprint first

Queries like `project = "PROJ"` are much faster than open searches. If using sprints, add `sprint = "Sprint Name"` to the query to significantly reduce the dataset.

Avoid overly broad JQL searches

Queries like `type != Epic` or `priority is not empty` scan your entire Jira instance. Add positive filters (e.g., `project in (PROJ1, PROJ2)`) to narrow scope and speed up execution.

Common pitfalls

Do

• Test your JQL in Jira's issue navigator before importing

• Use project keys in uppercase (e.g., project = "PROJ")

• Update your JQL as your Jira structure changes

• Pull only active issues regularly; archive historical data separately

Don't

• Share your Coupler.io data flow link with people who shouldn't see Jira data

• Use complex JQL without testing it first in Jira

• Export all custom fields if you only need a few; this slows down your flow

• Rely on exact field order—field positions may shift if custom fields are added/removed in Jira