Spreadsheet Lookup Fields for Jira

It is written for Marketplace documentation. It does not describe planned functionality that is not present in the app.

1. Product Overview

Spreadsheet Lookup Fields for Jira lets a Jira administrator turn spreadsheet-style reference data into a searchable Jira custom field.

The reference tables managed by the app are called catalogs.

Typical flow:

Spreadsheet or CSV data -> level mapping -> catalog -> published version -> Jira custom field

A catalog can be:

• a one-level flat list;
• a multi-level dependent picker where each level is filtered by the value selected before it.

Example source data:

Application -> Capability -> Owner
Portal      -> Payments   -> Finance
Portal      -> Billing    -> Finance
Mobile app  -> Payments   -> Platform

In a Jira issue field, users select values level by level. The saved value is displayed as a path, for example:

Portal / Payments / Finance

2. Who Uses the App

Jira administrators

• Open the app from Jira settings -> Apps -> Spreadsheet Lookup Fields.
• Create and maintain catalogs.
• Import spreadsheet or CSV data.
• Add, rename, and delete catalog options.
• Publish catalog versions.
• Create or reconnect Jira custom fields.
• Add the field to Jira Create/Edit/View screens.
• Configure the workflow post-function.

Jira issue users

• Use the Spreadsheet Lookup field on Jira issue Create/Edit/View screens.
• Choose catalog values level by level.
• See the selected path on the issue view.

JQL and issue search users

• Use the catalogValue(...) JQL function.
• Use indexed aliases such as CatalogValue, CatalogLevel1, CatalogName, and CatalogPath.
• Use the app's Find issues view to build JQL without typing it manually.

3. Opening the App

Open the app from Jira administration:

Jira settings -> Apps -> Spreadsheet Lookup Fields

The main Catalogs page contains:

• Import data - create a new catalog from pasted spreadsheet data or a CSV file;
• Blank catalog - create an empty catalog and add options manually;
• catalog search by catalog name, key, Jira field name, or Jira field ID;
• Health filter;
• a catalog table with:
• Catalog
• Health
• Options
• Levels
• Published
• Jira field

Each catalog row has an actions menu with:

• Open catalog
• Delete catalog

A catalog cannot be deleted while it is linked to a Jira field. The backend returns an error if deletion is attempted while an active Jira field link exists.

4. Catalog Health Statuses

The Health column summarizes what needs to happen next.

Empty

The catalog has no options. Import data or add options manually.

Needs structure

The catalog has data but does not have a valid picker level structure.

Needs publish

The catalog has draft changes that are not live for Jira fields yet. Open Publish and publish the next version.

Needs Jira field

The catalog has a published version but no linked Jira custom field.

Ready

The catalog is published and linked to a Jira field. The field reads the latest complete published catalog version.

Important: Ready does not prove that the field has already been added to all required Jira screens. The Jira field view reminds administrators to add the field to Create/Edit/View screens.

5. Limits

The current limits are enforced in the frontend and again on the backend.

If an import exceeds a limit, the app displays an error and the catalog is not created or updated.

6. Creating a Catalog from Data

On the Catalogs page, select Import data.

The Create from data workbench has five steps:

1. Source
2. Check data
3. Map levels
4. Review
5. Created

6.1 Source

In the Source step, you can:

• paste a table copied from Excel or Google Sheets;
• upload a CSV file.

The first row must contain column names. At least one data row is required. Header-only input is rejected.

The parser detects these delimiters:

• tab;
• comma;
• semicolon.

CSV-style quoted cells are supported, including embedded delimiters and escaped quotes. Empty lines are ignored. Ragged rows are padded with empty values so that the imported table has a consistent width.

The Source step displays import size usage:

• rows against the row limit;
• source data size against the data size limit;
• columns against the column limit.

The Use example data button fills the workbench with sample data.

Select Check data to create an import session and upload the source rows.

6.2 Check Data

The Check data step shows detected headers and data rows.

Displayed source row numbers start at 2 because row 1 is the header row.

Check that:

• columns were split correctly;
• headers are correct;
• rows look as expected.

Select Map levels to continue.

6.3 Map Levels

The Map levels step maps spreadsheet columns to Jira picker levels.

Example:

Level 1 -> Application
Level 2 -> Capability
Level 3 -> Owner

Rules:

• at least one level must be mapped;
• each level must use a different source column;
• mapped columns must exist in the source data;
• a deeper level cannot be filled when a parent level before it is blank.

Invalid example:

Application = blank
Capability  = Payments

This creates a blocking error because the Level 2 value has no Level 1 parent.

Duplicate path rows are merged into one picker option and shown as a warning, not a blocking error.

6.4 Review

The Review step checks:

• source row count;
• generated option count;
• skipped rows;
• blocking errors;
• warnings;
• import capacity problems.

The Review step also lets you set:

• catalog name;
• stable key, if edited in the advanced field.

The key is generated from the catalog name. The backend accepts letters, numbers, -, and _.

Select Create catalog to create the catalog.

6.5 Created

After successful creation, the catalog is created and the first version is published automatically. From the Created step, you can open the catalog or create another catalog.

7. Creating a Blank Catalog

On the Catalogs page, select Blank catalog.

The Create blank catalog side panel contains:

• Name
• Picker levels
• Description (optional)
• Advanced -> Stable key

Picker levels can be from 1 to 5.

• 1 - Flat list creates a one-level picker.
• More than one level creates a dependent picker where each additional level is filtered by the previous selection.

A blank catalog has no options at first. To use it in Jira:

1. Open the catalog.
2. Open Options and add options with Add option.
3. Publish the catalog in Publish.
4. Create or connect a Jira field in Jira field.

8. Catalog Workspace

Opening a catalog displays:

• Back to catalogs
• catalog name and description;
• metadata:
• option count;
• level count;
• published version or Not published;
• health status.

The left navigation contains:

• Source data
• Structure
• Options
• Publish
• Jira field
• Find issues
• Import history

8.1 Source Data

Source data shows imported source rows when they are available.

If source data is unavailable, the app shows an empty state with Replace data.

Available controls:

• Search source rows
• Column filter
• Density
• Compact
• Default
• Comfortable
• row and column count
• Add rows
• Paste rows
• Replace data

Mapped level columns show L1, L2, and so on in the table header.

Each source row has an Edit action. Edit opens a side panel where the administrator can correct the stored source-row values without replacing the whole spreadsheet.

Saving an edited row:

• saves the corrected row to the catalog draft;
• rebuilds the draft picker options from all stored source rows;
• preserves manually added options when they do not conflict with the rebuilt source options;
• marks the catalog as needing publish when the edit changes the draft.

If the edited value is in a picker level column, Jira users get the updated picker path only after the catalog is published. Already saved Jira issues keep the old saved path and details; the app does not update existing issue values automatically. To refresh one issue, edit or save this field again on that issue.

If the edit changes only a Catalog details column, the picker choices stay the same. New selections and future issue edits can use the updated details after publish. Already saved issues keep their old detail snapshot until the field is edited or saved again.

The app blocks a row edit when it would duplicate another source row, leave a deeper level without its parent value, conflict with a manual option, exceed catalog limits, or when generated options have been manually edited in a way that no longer matches Source data. For larger catalogs, the side panel may skip the live option-count preview, but full validation still runs before anything is saved.

Add rows and Paste rows open an inline row-entry area. Administrators can type values directly or paste cells copied from Excel or Google Sheets. Pasted values fill across and down from the focused field using the catalog's existing source-column order. If the pasted first row matches the existing source headers, the app ignores that header row.

The inline row entry is intended for small additions and accepts up to 100 rows at a time. Source columns wrap inside each new row so wide source tables can be edited without changing the source table shape. It uses the catalog's existing source columns and existing level mapping. It does not change Jira until the catalog is published.

Before saving added rows, the app checks:

• blank trailing rows;
• duplicate source rows;
• missing parent values in dependent levels;
• source row, option, byte, column, level, and cell-length limits.

Exact duplicate source rows are skipped. If at least one new row remains, the app appends the rows to draft source data and rebuilds the draft option tree from the combined source table.

If the catalog also contains manually added options, the app preserves them during Add/Paste rows. If a new source row would conflict with a manual option's stable key or duplicate the same option under the same parent, the app stops the save and asks the administrator to resolve the manual option first.

If existing source-generated options were manually renamed or deleted in Options, Add/Paste rows stops instead of silently rebuilding and overwriting those option edits. Use Replace data when the source table should become the new source of truth.

Replace data opens the update flow and replaces the catalog's draft source data.

8.2 Structure

Structure shows how source columns map to dependent picker levels.

If stored source rows are available, the mapping is editable. If they are not available, the app displays an information message and asks the administrator to use Replace data to store source rows and unlock re-mapping.

The editable Structure view contains:

• Level mapping table;
• spreadsheet column selector for each level;
• unique value count;
• blank cell count;
• sample values;
• issue count;
• Unmapped columns panel;
• Catalog details panel;
• Generated option tree preview.

Mapping cannot be saved while blocking errors exist. After a successful re-map, the generated options are recalculated and the catalog has draft changes that must be published.

Catalog details lets an administrator choose non-picker spreadsheet columns to show after a Jira user selects a complete picker path. Details are read-only in Jira and are saved as part of the Spreadsheet Lookup field value. They do not create separate Jira fields and they do not change the catalogValue JQL path search.

Catalog details can use up to 8 source columns. Picker level columns cannot be used as details. If duplicate source rows generate the same picker path, configured detail values for that path must match before the catalog can be published.

8.3 Options

Options shows the picker options generated from source data and structure, plus any manually added options.

Available controls:

• Search options
• Level filter
• Parent filter
• Density
• Replace data
• Add option

Table columns:

• Display name
• Path
• Level
• Parent
• delete action

Display names can be renamed inline by selecting the name. Renaming creates draft changes. Publish the catalog for Jira fields to use the new name.

Deleting options:

• a parent option cannot be deleted while it still has child options;
• delete child options first;
• publish the catalog after deletion.

8.4 Add Option

Add option opens a side panel with:

• Display name
• Level
• Parent option for dependent levels;
• Advanced -> Stable key

Rules:

• display name is required;
• stable key is required;
• dependent level options require a parent from the previous level;
• if the previous level has no parent options, the UI shows a warning;
• option display names are limited to 255 characters;
• stable keys may contain letters, numbers, -, and _;
• duplicate display names under the same parent are rejected;
• a catalog cannot exceed 15,000 options.

After adding an option, publish the catalog.

8.5 Publish

Publish controls which catalog version Jira fields use.

If there are no options, the app displays No options to publish and offers Import data.

If the published version matches the current draft, the app displays:

Jira is up to date

If draft changes exist, the app displays the next version, for example:

Publish version 3

Publishing means:

• draft options become a published catalog version;
• linked Jira fields start using the new published version;
• draft changes are no longer only inside the admin app.

Discarding draft changes

If draft changes turn out to be wrong, Discard draft changes returns the catalog to the version Jira already uses. The action sits next to the publish button and appears only while the catalog has draft changes.

Discarding restores, from the last publish:

• the picker options, including their display names and level structure;
• the source rows;
• the level mapping and level count;
• the catalog details configuration.

Everything created in the draft since that publish is deleted, including option renames, manually added options, re-mapped levels and detail changes. This cannot be undone, so the app asks for confirmation and shows what the catalog goes back to.

Jira users see no change, because they were already using the published version. After discarding, the catalog status returns to Jira is up to date, and Import history records the action as Discarded draft.

Discard is available only when the catalog was published by an app version that stores the published draft state. For a catalog published before that, the Publish view explains that discard becomes available after the next publish of that catalog.

8.6 Jira Field

Jira field shows whether the catalog is linked to a Jira custom field.

A catalog must have at least one published version before a Jira field can be created or connected.

If no field is linked, available actions are:

• Create Jira field
• Link existing Jira field

Create Jira field creates a new Jira custom field of this app's Spreadsheet Lookup field type and binds it to the catalog.

The Create Jira field modal contains:

• field name;
• description.

Link existing Jira field requires a Jira field ID in this form:

customfield_10042

The existing field must be a Spreadsheet Lookup field from this Forge app. If the field is already linked to a different catalog, the backend rejects the request.

When a field is linked, the view shows:

• Linked status;
• Jira field name;
• Jira field ID;
• Copy field ID;
• Reconnect;
• Field readiness:
• Published options;
• JQL search;
• Jira screens.
• Field behavior:
• Auto-fill single remaining choices;
• Also auto-fill the first level.

After creating or connecting the field, a Jira administrator must add the field to Jira Create, Edit, and View screens. The app provides Open field settings.

The app explicitly states that Jira does not render this picker on workflow transition screens. Do not use the field as a normal editable field on workflow transition screens.

Auto-fill single remaining choices is off by default. When enabled for the catalog's linked Jira field, the picker automatically selects the next level only when the selected parent has exactly one child option. It continues through deeper levels while each next level has exactly one option.

Also auto-fill the first level is a separate option. Use it only when the field should always start with the single top-level option. Auto-fill changes the picker selection in the edit UI; Jira still saves the field through the normal issue create/edit save action.

8.7 Find Issues

Find issues helps build JQL without writing it manually.

If the catalog has no Jira field, the app displays:

Create the Jira field before searching

If the field is linked, the view contains:

• Picker builder with Level 1, Level 2, and so on;
• JQL preview;
• Open issue search;
• Copy JQL;
• Catalog;
• Selected levels;
• Published version.

Leaving deeper levels empty creates a broader search. For example, selecting only Level 1 searches for every issue using that top-level value.

The current Search coverage message is:

New issues and edited field values are searchable automatically. If an older issue is missing from results, open it and save this field once to refresh its catalog path.

8.8 Import History

Import history shows previous completed source imports for the catalog.

Columns:

• Imported
• Source
• Source rows
• Options
• Mapping
• Status

Source labels:

• Pasted data
• CSV file
• Added rows
• Published version, used when a draft was discarded and the catalog was restored from its published version. The action for that entry is Discarded draft.

History is shown newest first. The current UI indicates that the latest 250 imports are retained.

9. Adding or Replacing Catalog Data

For small additions to an existing catalog, use Source data -> Add rows or Paste rows.

This appends new rows to the draft source table and rebuilds the draft options from all stored source rows. Existing source rows stay intact. Jira fields continue using the latest published version until the administrator publishes the draft.

To replace all source data in an existing catalog, use Replace data.

The update flow replaces the catalog's draft source data and regenerates options from the selected mapping. After a successful update, the catalog usually needs publishing because the Jira field continues to use the last published version until the administrator publishes the new draft.

The update flow includes:

• source data entry;
• level mapping;
• review;
• updated state.

If validation finds blocking errors, the update is not applied until the errors are fixed.

10. Using the Jira Field on Issues

On Jira issue Create/Edit/View screens, the Spreadsheet Lookup field works as a dependent picker.

In edit mode:

• the field loads published options;
• Level 1 is available immediately;
• each next level becomes available after its parent is selected;
• selections can be cleared;
• Selected path is shown when a value is selected.
• configured catalog details are saved with the selected value after a complete path is selected.

In issue view mode:

• if no value is selected, the view shows No picker option selected;
• if a value is selected, the path text is shown;
• configured catalog details are shown below the path text.

If the field is not connected to a catalog, the edit UI explains that the Jira field is not connected to a Spreadsheet Lookup Fields catalog and asks the user to contact a Jira administrator.

If the catalog is not published or has no options, the edit UI explains that the catalog must be published or populated before it can be used.

10.1 Jira Service Management customer portals

The field also works on JSM customer portal request forms, so a customer can pick a catalog path when they raise a request. It behaves as it does on a Jira screen: one select per level, each level filtered by the level above it.

Portal access is off for every catalog until an administrator turns it on. This is deliberate. Catalogs often hold internal reference data, and portal customers can include people outside your organisation.

To turn it on, open the catalog, go to Jira field, and use the Customer portal section:

• Available on customer portals. Everyone who can raise a request on any portal on this site can then read every option in this catalog. Leave this off for catalogs that hold internal reference data.
• Also share catalog details with customers. Adds the extra spreadsheet columns of the selected row. Leave this off if any of those columns are internal, such as an owner email or a contract value.

The second switch depends on the first: turning portal access off also stops sharing details.

Two things to know before you switch it on:

• Access is per catalog, not per project or per request type. A catalog you share is readable by customers of every portal on the site, not only the one you added the field to.
• Customers do not need a Jira licence, so sharing a catalog is a decision about the data in it rather than about who has a Jira account.

Until a catalog is shared, a customer who meets the field on a portal form sees a short message saying the field is not available and suggesting they contact the service desk team. Portal messages never name the app, the catalog or a Jira administrator, because none of those mean anything to a customer.

Values chosen on a portal are stored on the request like any other value, and become searchable with catalogValue() a few seconds after the request is created.

11. JQL Search

11.1 Recommended Function: catalogValue

The app defines this JQL function:

catalogValue(catalog, level1, level2, level3, level4, level5)

Use it with issue in or issue not in.

Examples:

issue in catalogValue("Application")

Finds issues that have a value in the Application catalog.

issue in catalogValue("Application", "Portal")

Finds issues with the Application / Portal path prefix.

issue in catalogValue("Application", "Portal", "Payments")

Finds issues with a more specific path.

issue not in catalogValue("Application", "Portal")

Excludes issues with that path prefix.

The function expands to a precise CatalogPath token search where catalog name and path values are bundled into one atomic token. This avoids cross-matches when one issue contains more than one Spreadsheet Lookup field.

11.2 Indexed JQL Aliases

The app indexes the issue entity property catalogfield with these aliases:

Examples:

CatalogName = "Application"

CatalogValue = "Payments"

CatalogLevel1 = "Portal"

CatalogFieldText ~ "Payments"

Important: CatalogLevel*, CatalogValue, and CatalogName are aggregated across all Spreadsheet Lookup fields on the issue. If an issue may contain multiple catalog fields, prefer catalogValue(...) because it uses the atomic CatalogPath token.

11.3 When Issues Become Searchable

Indexing happens:

• after an issue field edit when an issue ID is available and the user has EDIT_ISSUES permission;
• after issue creation through the avi:jira:created:issue trigger, because the issue does not exist yet while the Create screen is open;
• after the workflow post-function updates a field.

If an older issue is missing from search results, the app recommends opening the issue and saving the field once to refresh the catalog path index.

12. Workflow Post-Function

The app provides this Jira workflow post-function:

Set Spreadsheet Lookup field

Description:

Set, copy, or clear a Spreadsheet Lookup field after a workflow transition.

It is available for company-managed projects.

12.1 Prerequisites

Before configuring the post-function:

• the catalog must be published;
• the catalog must be linked to a Jira field;
• the target field must be an active Spreadsheet Lookup field link.

If no linked fields exist, the configuration UI shows:

No linked fields

12.2 Target Field

First, choose the Target field. The UI shows the field name and published version.

If the target catalog is not published, the UI warns:

Publish this catalog before the workflow can set values from it.

12.3 Actions

There are three actions.

Set fixed value

Always sets one specific catalog path. The UI shows Catalog value with Level 1, Level 2, and so on. These selectors work like the dependent picker.

Copy from field

Copies the value from another Spreadsheet Lookup field. The source field must:

• be different from the target field;
• use the same catalog as the target field;
• have a published catalog version.

If the source field is empty, the target field is cleared.

Clear field

Removes the value from the target field.

12.4 Runtime Validation

The post-function validates configuration again on the server:

• mode must be fixed, copy, or clear;
• target field ID must be customfield_...;
• target catalog ID must be present in the saved configuration;
• the target field must still be linked to the catalog saved in the workflow configuration;
• fixed mode requires a leaf key for the chosen catalog value;
• copy mode requires a source field ID that is not the target field;
• fixed values are read from the latest published catalog version;
• copy mode verifies that source and target fields use the same catalog;
• after updating the field, the post-function updates the issue property index.

If the target field has been relinked to another catalog, reconfigure the post-function. If the fixed option or copied source value is no longer available in the published catalog, the post-function fails. Copy mode also rejects source values that do not carry the current catalog identity.

12.5 Timing

The post-function runs in the background after the transition, so the field does not change at the exact moment the transition completes. A few seconds is normal.

This is most visible on the transition that creates an issue. Jira stores the value chosen on the Create screen first, so the issue can briefly show that value before the post-function replaces or clears it. Refresh the issue after a few seconds before concluding that the post-function did not run.

13. Data Storage and Security Behavior

The current implementation uses:

• Forge SQL for catalogs, options, published versions, import sessions, import history, source rows, field links, and the published draft snapshot used to discard draft changes;
• the Jira issue field value for the selected catalog value;
• the Jira issue entity property catalogfield for JQL indexing.

The app manifest does not define external egress, remotes, or webtriggers.

The app declares these scopes:

• manage:jira-configuration
• read:jira-work
• write:jira-work

Catalog administration resolvers verify Jira ADMINISTER permission before reading or changing catalog administration data. Runtime issue property sync verifies EDIT_ISSUES permission for the issue before writing the app's issue property.

Import sessions are tied to the creating admin account ID. An unfinished import session can be resumed or changed only by the same admin account. Import sessions older than 24 hours are purged opportunistically when a new import starts, and import-session metadata tied to a deleted catalog is deleted with that catalog.

13.1 Trust and Support Links

The production app is built on Atlassian Forge and is eligible for Runs on Atlassian. It has no vendor-hosted app servers, no external connectors, no external analytics, no AI calls, and no customer catalog data egress from the Forge app. Forge custom metrics count high-level setup milestones only and do not include catalog values, issue content, spreadsheet rows, names, or emails.

For a concise security, privacy, and support overview, see Trust and support. For the public privacy statement, see Privacy policy. For help, bug reports, security/privacy reports, and feature requests, use the support portal.

14. Troubleshooting

Catalogs could not load

The admin page could not complete setup or read catalogs. Use Try again. In the Forge development environment, Reset development data may be available.

The picker is empty

Possible causes:

• the Jira field is not connected to a catalog;
• the catalog is not published;
• the catalog has no options;
• the user cannot read the active catalog-field binding.

A new option does not appear in the Jira issue field

Adding, renaming, deleting, updating, or re-mapping options creates draft changes. Open the catalog and use Publish.

Draft changes were a mistake

Open the catalog, go to Publish, and use Discard draft changes to return the catalog to the published version Jira is already using. If the button is not shown, the catalog was published before the app stored the published draft state; publish once, and discard is available from then on. Jira users are unaffected either way, because draft changes never reach them before publishing.

A Jira field cannot be created

The catalog must be published first. Creation can also fail if Jira's field creation API rejects the request.

An existing field cannot be connected

The field ID must be in the customfield_... format and must belong to this app's Spreadsheet Lookup field type. The field must not already be linked to another catalog.

A catalog cannot be deleted

The catalog cannot be deleted while it is linked to a Jira field.

An option cannot be deleted

If the option has child options, delete the child options first.

JQL does not return an issue

Check:

• the issue field has a saved value;
• the catalog is published;
• the JQL uses the correct catalog name and path values;
• older issues may need the field to be saved once to refresh the index.

Workflow post-function does not do what was expected

Check:

• whether a few seconds have passed and the issue has been refreshed (see 12.5), especially on the transition that creates an issue, where the value from the Create screen is stored first;
• the target field is still linked;
• in copy mode, the source field uses the same catalog as the target field;
• the fixed option still exists in the latest published catalog version;
• the workflow transition event contains an issue ID.

15. Administrator Best Practices

• Use catalog names that are understandable to JQL users because catalogValue(...) uses the catalog name.
• Before publishing, review Options and Find issues.
• Draft work is reversible: if an edit turns out wrong, use Discard draft changes on the Publish view instead of undoing edits by hand or re-importing the spreadsheet.
• For multi-level catalogs, do not leave a parent level blank before a filled child level.
• Use Import history to see what mapping was used in previous imports.
• After creating a field, add it to Jira Create/Edit/View screens.
• Do not add this field to workflow transition screens as a normal editable field. Use the workflow post-function when a transition should set, copy, or clear the value.