User guide

Excel to Jira Importer & Updater - User Guide

Use this guide when you need to turn an Excel workbook into reviewed Jira issues, update issues from a later workbook version, or fill an existing workbook with selected Jira values.

The guide is written for project managers, product owners, business analysts, Scrum Masters and delivery teams who already work in Excel and Jira.

Comparing Jira's native CSV import with a workbook-aware workflow? Start with How to import Excel to Jira.

Updated July 28, 2026 ยท Nothing changes in Jira until review and confirmation.

Validation preview showing rows ready to import and final Jira values.
Review final Jira values before importing.

Quick start

Import Excel into Jira

  1. Open the app from the Jira project where issues should be created or updated.
  2. Choose Import or update Jira from Excel.
  3. Upload the workbook and choose the worksheet and header row.
  4. Choose the issue structure, map fields and clean values where needed.
  5. Review the final Jira changes, select importable rows and confirm the import.

Fill Excel from Jira

  1. Choose Fill Excel from Jira.
  2. Select an existing workbook or start with a clean one.
  3. Choose Jira issues and map Jira values into workbook columns.
  4. Review the workbook cell changes.
  5. Download the updated workbook. Jira issues are not changed.
Safe working rule Uploading a workbook only prepares a preview. Jira issues are created or updated only after you review the planned changes and confirm the import.

When to use it

Use the app when your team already has backlog, scope or planning work in Excel and wants to move it into Jira with a review step instead of copying rows by hand.

  • Discovery outputs that need to become Jira issues.
  • Client or stakeholder scope workbooks.
  • Delivery plans maintained in Excel.
  • Repeated workbook versions where new rows should be added and known rows may need updates.
  • Workbooks that need cleanup before Jira can accept field values.

Use the preview as the decision point before confirming an import, especially when updating existing Jira issues.

Before you start

Prepare the workbook

Use an Excel .xlsx workbook. The best workbook structure has one row per Jira issue, clear column names and a Summary column. If you plan to upload later versions of the same workbook, include a stable ID column such as Request ID, Backlog ID or External reference.

  • A header row should contain column names such as Summary, Description, Issue Type, Priority and Due Date.
  • Data rows should start below the header row.
  • Avoid merged cells and hidden logic that makes final values hard to understand.
  • Use consistent names for priorities, components, versions and users.

Check the Jira project

Open the app from the Jira project where work should be created. Check that the project contains the issue types and fields you want to use. Your normal Jira permissions still apply, so you need permission to create or edit issues in that project.

Access control

After installation, the app can be open to Jira users who can access the project page. Jira administrators can restrict app access to selected groups.

  1. Open the Excel to Jira Importer configuration page from Jira app administration.
  2. Change access mode from Open by default to Restricted.
  3. Open Jira settings, then System, then Global permissions.
  4. Grant Use Excel to Jira Importer to the group that should use the app.

This app-specific permission does not replace Jira project permissions. A user may be allowed to open the app and still be blocked by Jira if they cannot create or edit issues in the selected project.

Import Excel to Jira

1

Choose the import workflow

The first screen lets you choose between importing Excel into Jira and filling Excel from Jira. For import work, choose Import or update Jira from Excel.

Start screen with Import or update Jira from Excel selected.
Start from the project page and choose the direction of work.
2

Upload the workbook

Drop the workbook into the upload area or choose it from disk. Jira is not changed at this point.

Workbook upload screen for choosing an Excel file.
The upload step prepares the workbook for review. It does not create Jira issues.
3

Choose worksheet and header row

Select the worksheet that contains the backlog, then choose the row that contains column names. Rows below that header row are treated as source rows.

Worksheet selection screen with a selected header row.
Choose the sheet and the row that contains the workbook column names.
4

Reuse a saved setup when it fits

If the workbook looks similar to one used before, the app can suggest a saved import setup. You can reuse it, adjust it, choose another setup or start fresh.

Saved import setup suggestion for a familiar workbook.
Saved setups speed up repeated imports, but the preview should still be reviewed.
5

Choose issue structure

Choose whether each Excel row should become one separate issue, whether parent references come from workbook columns or whether the app should build hierarchy from several columns.

Issue structure screen using one Jira issue per Excel row.
Flat import is the safest default when each row is one independent work item.
Issue structure screen using parent references from workbook columns.
Use parent-from-column when rows in the workbook identify their parent rows.
Issue structure screen using multiple hierarchy columns.
Use multi-column hierarchy when the workbook stores levels such as Epic, Story and Task in separate columns.
6

Map fields and preview values

Map required Jira fields first, especially Summary and Issue Type when the project requires it. Optional fields can be mapped now or left unmapped.

Field mapping screen with workbook columns mapped to Jira fields.
Map workbook columns to Jira fields and keep unmapped fields out of the import.
Workbook preview modal showing source rows and highlighted columns.
Use the workbook preview to confirm that selected columns contain the values you expect.
7

Review relationships

Leave relationships off unless the workbook has reliable references to other Jira issues or other rows in the same workbook.

Relationships step with relationship creation turned off.
The safest default is to import issues without creating links.
Relationships step with relationship configuration enabled.
Turn relationships on only when references are stable enough to review.

Field mapping

Mapping connects a workbook column to a Jira field. For example, the workbook column Title can be mapped to Jira Summary.

Required fields

Jira always requires Summary. Your project may require additional fields depending on issue type. If a required mapped value is missing, validation blocks that row before import.

Optional fields

Optional fields can stay unmapped. If a field is not mapped, the app does not send a value for it. If a mapped optional field is empty in one row, validation shows what will happen for that row.

Common field behavior

  • Issue Type values must match issue types available in the current Jira project.
  • Priority, Components and Fix versions should match values configured in Jira.
  • User fields work best with email addresses or clear display names.
  • Labels can contain several values when they are separated consistently.
  • Dates and numbers should use a consistent format, especially when values come from text.

Issue structure

The issue structure step decides how imported rows relate to other rows and to existing Jira issues. Choose this before field mapping because parent rules can affect validation.

Flat imports

Use Simple: one Jira issue per Excel row when each row should become one Jira issue. You can use one default issue type for all rows or map an Issue Type column.

Default Jira parent

Use a default parent when all imported rows should be placed under the same existing Jira issue, depending on your Jira project configuration. Sub-task rows require a valid parent.

Parent from an Excel column

Use this when one column says which row is the parent and another column contains the value used to identify that parent row. Parent references should be unique enough to avoid ambiguity.

Multi-column hierarchy

Use this when hierarchy levels are stored in separate columns. The first selected hierarchy column becomes the top level, and each next selected column becomes a child level below it. Repeated full hierarchy paths are shown as skipped so duplicate issues are not created for the same generated path.

Description Builder

Jira Description can come from one workbook column or be assembled from several columns.

Field mapping step with one Description column selected.
Use one column when the workbook already contains a ready Jira Description.
Description Builder modal with several workbook columns selected.
Combine several columns when context is spread across the workbook.
  • Section headings come from workbook column names.
  • Empty cells are skipped.
  • Section order in the builder is the order used in Jira.
  • Unmapped columns can be appended when they contain useful context.

Use Description Builder for extra context instead of creating unnecessary Jira custom fields for one import.

Value cleanup

Value cleanup adjusts a workbook value before it is sent to Jira. Use it when a cell contains extra notes, prefixes, brackets, dates, codes or labels that need to be cleaned for one mapped Jira field.

Value cleanup modal using the Take text before rule.
Take text before or after a marker.
Value cleanup modal removing bracketed text.
Remove bracketed notes.
Value cleanup modal extracting a date from text.
Extract dates from longer text.
Value cleanup modal replacing workbook values with Jira values.
Normalize workbook labels to Jira values.
Advanced custom regex rule in the Value cleanup modal.
Use the advanced custom rule only when the simpler cleanup options are not enough.

Available cleanup patterns

  • Import the full value.
  • Take text before, after or between markers.
  • Remove text inside brackets.
  • Extract a date, number or Jira issue key.
  • Replace exact workbook values with Jira-ready values.
  • Use an advanced custom text pattern when needed.

Always check the cleanup preview. A rule can produce a value that looks valid but is not the value you intended to import.

Review and validation

Validation is the last checkpoint before Jira changes. It shows which rows are ready, blocked or skipped and which Jira values will be sent.

Validation preview showing rows ready to import and final Jira values.
Review final Jira values and row-level messages before importing.
Large validation table modal.
Open the large view when the table needs more space.

How to read the review

  • Added rows create new Jira issues.
  • Updated rows change existing Jira issues matched by the setup.
  • Skipped rows are not imported, usually because they are duplicate generated hierarchy paths or intentionally unchanged rows.
  • Missing data and Other errors need attention before those rows can be imported.

Outdated review

If you change the workbook, worksheet, mapping, issue structure, relationship rules or duplicate/update behavior after reviewing, run review again before importing.

Diagnostic JSON

The review screen includes a Diagnostic JSON link for support investigations. It may contain workbook values, so anonymize sensitive content before sharing it.

Relationships and updates

Issue relationships

Relationship setup controls whether the import should create Jira issue links after issues are created or updated. Keep it off unless the workbook has reliable references.

Setting Use when Watch out for
Existing Jira keys The workbook contains issue keys such as DEMO-123. Keys must exist and be visible to the current user.
Workbook row references One column points to another row in the same workbook. The target column should contain stable, unique values.
Missing target behavior You want missing relationship targets to be warnings or blockers. Use blocking behavior when missing links would make imported work misleading.

Repeated imports and updates

The app can recognize later uploads from stable row identifiers and import metadata. When update behavior is used, only mapped fields in the current setup are updated. The review screen shows which rows will create, update, skip or fail before the import starts.

Update mode changes existing Jira issues Check the review carefully and confirm that the correct rows are marked as updated before importing.

Saved setups

The app can suggest a saved import or fill setup when a workbook has a familiar structure. File names do not have to be identical; a later workbook version can still match when the sheet and columns are similar.

A saved import setup can include mappings, Description Builder, Value cleanup, hierarchy, relationship rules, duplicate/update behavior and estimate settings. A saved fill setup can include worksheet choice, column names row, Jira-to-Excel mapping and relationship mapping.

Saved setups are convenient, but they are not a substitute for review. Always check that the workbook columns still mean the same thing.

Import report

After import, the report shows created, updated, skipped and failed rows. It also shows Jira issue keys where available and row-level messages explaining what happened.

Import progress screen shown while Jira changes are running.
Keep the page open while import is running.
Import report with created issues and row statuses.
Use the report to confirm the result and open created or updated Jira issues.
Large import report table modal.
Open the detailed report when you need more space to inspect rows.

You can keep the report for your own records and use row messages when discussing follow-up fixes with your team.

Fill Excel from Jira

Use Fill Excel from Jira when you want selected Jira values written into a workbook. This workflow does not change Jira. It prepares a reviewed workbook for download.

Start screen with Fill Excel from Jira selected.
Choose Fill Excel from Jira when Jira should provide values for the workbook.
Fill Excel workflow workbook selection screen.
Select an existing workbook or start from a clean one.
Saved fill setup suggestion for a familiar workbook.
Reuse saved fill setup when the workbook structure matches.
Fill Excel workflow worksheet and column names row selection.
Choose the worksheet and column names row.
Fill Excel workflow Jira issue selection screen.
Select which Jira issues should provide values.
Fill Excel workflow mapping Jira fields to workbook columns.
Map Jira values into workbook columns.
Fill Excel workflow relationship mapping screen.
Relationship mapping writes link information into Excel; it does not create Jira links.
Fill Excel workflow review screen for workbook cell changes.
Review which workbook cells will receive Jira values.
Large workbook change preview modal.
Use the full preview for a wider workbook view.
Fill Excel workflow download-ready screen.
Download the reviewed workbook after preview.

Troubleshooting

Problem What to try
The workbook was not read. Use an Excel workbook with a clear worksheet and visible values. If the file is very large, try a smaller sample first.
The wrong row is used as the header. Go back to worksheet selection and choose the row that contains column names. Data starts below that row.
A required Jira field is missing. Map the field or fill the missing workbook cells. Required fields can change by issue type.
Date validation fails. Check the workbook date value and the selected cleanup date format.
Value cleanup returns an empty value. Open the cleanup preview and adjust the marker, date rule, replacement list or fallback behavior.
The hierarchy does not look right. Check the selected hierarchy columns, issue types and how empty cells should be handled.
Some rows are skipped. Read the row message. Skipped rows are often duplicate hierarchy paths, unchanged rows or rows intentionally excluded by the setup.
An expected Jira field is missing. Check the project and issue type configuration. Some fields depend on project setup or may not be available for the selected issue type.
The import failed. Read the report message. Common causes include Jira permissions, rejected field values, missing parent issues and invalid field options.

FAQ

Does uploading a workbook create Jira issues?

No. Uploading only prepares the file for review. Jira issues are created or updated only after validation and import confirmation.

Can I import only selected rows?

Yes. On the review screen, select the importable rows you want to import. Rows with blocking errors cannot be imported until fixed.

Can the app update existing Jira issues?

Yes, when the setup can match workbook rows to existing issues or previous import metadata. Review shows updated rows before import.

Will update mode change every Jira field?

No. Update mode changes only fields mapped in the current setup.

Does Fill Excel from Jira change Jira issues?

No. It reads selected Jira values, previews workbook cell changes and downloads an updated workbook.

Does the app use product analytics?

When product analytics is configured, the app may send sanitized usage and reliability events such as workflow steps, actions, results and aggregate row, column and error counts. Product analytics is designed not to include Excel cell values, Jira issue text, issue keys, project names, user names, email addresses or support messages. See the privacy policy and data processing summary for details.

Why do I see an access-restricted screen?

Your Jira administrator has restricted access to the app. Ask an administrator to grant your group the Use Excel to Jira Importer global permission.

Glossary

Workbook
An Excel file containing one or more worksheets.
Worksheet
A tab inside a workbook.
Header row
The row that contains column names used for mapping.
Mapping
The connection between a workbook column and a Jira field.
Issue structure
The choice that controls whether rows are independent issues, children of a parent or part of a generated hierarchy.
Value cleanup
A rule that adjusts one mapped workbook value before review and import.
Validation
The review step that shows ready, blocked and skipped rows before Jira changes are confirmed.
Saved setup
A reusable setup for a similar workbook structure.