File Field for Jira
Setup & usage documentation

1. Overview

File Field for Jira – Attachment & Document Custom Fields adds a dedicated file-upload custom field to Jira issues and Jira Service Management request forms — separate from Jira’s single built-in attachment box, with rules you control.

Create as many fields as you need, each with its own allowed file types, size and count limits, and its own choice of storage mode. A field’s configuration lives with the field itself, so a “Design assets” field and a “Signed contract” field on the same issue type can enforce completely different rules.

At a glance

2. Prerequisites

3. Installation

1. Open the app’s listing on the Atlassian Marketplace.
2. Click Try it free (or Get it now) and choose the Jira site to install on.
3. Confirm the requested permissions. They are listed in full in section 5.
4. Wait for the install to complete. Nothing appears on any issue yet — the field itself does not exist until you create one, which is a separate step. See section 4.

4. Creating the Field

Installing the app adds a new custom field type to Jira — it does not add a field to any issue by itself. Creating and placing an actual field takes the same admin chain as any Jira custom field, plus one extra step on team-managed projects that is easy to miss.

Where the field appears

5. Permissions

The app requests six scopes, and no others:

Runs on Atlassian

The app declares no external domains and makes no network request to any third party. Portable-mode file bytes are ordinary Jira attachments; Private-mode file bytes live in Forge Object Storage — a store Atlassian operates on the app’s behalf, not a service Contextra Labs runs.

6. Configuration

Open the field’s configuration screen (see section 4). Configuration is per field — two File Field custom fields on the same issue can carry completely different rules.

Storage mode

Choose one of two radio options. The tradeoff is stated on the screen itself, not left to the documentation:

Limits

Allowed file types

“Leave every box unchecked to allow any file type.” Four categories are offered:

These decide what an admin can restrict a field to, not the security boundary by itself — every upload is also checked that its content actually matches its claimed extension, regardless of category. See section 10.

Preview

“Show inline previews for images and PDFs” — on by default. When off, every file downloads instead of previewing, even images.

Test your rules

A separate, visually distinct panel below Save. It does not change the field’s configuration — it only answers a question about it.

This is the fastest way to check a size or type rule without needing to construct a real oversized or disallowed file — used in the walkthrough in section 10.

7. Uploading & Managing Files

On an issue with the field, or on a JSM request form, the edit view shows every file already attached, an Add file button, and — while the field is empty — a one-line summary of its active rules, for example:

1. Click Add file (or Add files, if more than one is allowed) and choose one or more files.
2. Each file is checked against the field’s rules before anything is sent over the network. A file that fails shows its rejection reason immediately, with a Dismiss button.
3. A file that passes uploads with a progress spinner next to its name, then joins the list with its size shown alongside.
4. Click Remove next to any file to take it out of the field.

A rejected upload, reproduced

If the licence or evaluation is inactive, the field becomes read-only: “An active licence is required to add or remove files. Existing files remain visible and downloadable.”

8. Viewing & Downloading

Anyone who can view the issue sees the field’s read-only view: a list of file names and sizes, or “No files attached.” if the field is empty.

1. Click any file name to open it.
2. Images open in an inline preview dialog, if previews are enabled for the field.
3. Every other file type downloads immediately with one click.
4. Click Download all as ZIP, shown whenever the field has files, to bulk-export every file in the field into a single archive — works in either storage mode.

If a file was removed directly in Jira — outside this field, for example through Jira’s own attachment panel in Portable mode — it stays listed with its name struck through and labelled “Removed in Jira”, and a notice appears: “Some files were removed directly in Jira and are no longer available through this field.”

9. JSM Portal Requests

A File Field added to a Jira Service Management request type appears on the portal request form for requesters, using the exact same rules configured for the field — the same allowed types, size and count limits, and the same storage mode. Agents see the same field, with the same read-only view described in section 8, on the portal’s request view.

There is nothing JSM-specific to configure: a field behaves identically whether it is reached from the Jira issue view or from a customer-facing portal.

10. Sample Test Files

Three small files for validating a field’s upload rules end to end, plus one rule you can test without uploading anything at all.

Step 1 — restrict the field to Documents

In the field’s configuration (section 6), check only Documents under Allowed file types, leave Max size per file at its 10 MB default, and Save.

Step 2 — upload the sample PDF

On an issue carrying the field, click Add file and choose filefield-sample-document.pdf. It should upload and appear in the list.

Step 3 — upload the sample PNG (expect a rejection)

Try filefield-sample-image.png next. Since only Documents are allowed, it should be rejected immediately, before any network request:

Step 4 — allow Images too, then retry

Back in configuration, check Images alongside Documents and Save. Upload filefield-sample-image.png again — it should now be accepted, and clicking it in the field’s view should open an inline preview rather than a download.

Step 5 — the renamed file (expect a spoof rejection)

Upload filefield-sample-image-renamed.pdf. Its bytes are a PNG, but its extension claims .pdf. Extension and category checks pass — PDF is an allowed Document — but the content check catches the mismatch:

Step 6 — the size rule, with no file at all

Use Test your rules in configuration instead of constructing a large file. Enter file name scan.pdf, MIME type application/pdf, size 15000000 (roughly 15 MB) against the 10 MB default, and click Test:

Expected results

Worth noting for the third row: the spoof check compares file bytes against signatures it recognises, then compares that against the claimed extension. A renamed text file is not caught this way — there is no known signature to disagree with — which is why this walkthrough uses a renamed binary image instead.

11. Storage Modes In Depth

Neither mode is a general recommendation over the other, and neither restricts who can access a file beyond Jira’s own issue-view permission — Portable suits files that should behave exactly like any other Jira attachment; Private suits files that need to stay isolated from Jira’s own attachment integrations, or that must be added before the issue exists.

12. Limitations

These are published rather than buried, because finding them after paying is worse for everyone.

13. Troubleshooting

14. Support

• Email support@contextra-labs.com — questions, bug reports and feature requests all go to the same place.
• Support page — response times and what to include in a report.
• Atlassian Marketplace listing ↗
• Privacy policy · Terms & EULA

When reporting a problem with a specific field, the most useful details are the field’s name, its configured storage mode, and the exact message it showed.