Documentation / Marketplace reviewer guide

Marketplace reviewer test guide

Use this sequence to verify installation, authorization, manual and API catalogs, licensing, Jira field behavior, and data retention for VersionSelect for Jira.

Prerequisites

• A Jira Cloud test site where the submitted app version can be installed.
• One Jira administrator account and, for the authorization check, one non-administrator account.
• A company-managed test project with permission to add a global custom field to Create, Edit, and View screens. A team-managed project can also be used after adding the global field in project Fields.
• The privately supplied synthetic API URL and credential. They contain test catalog data only and are not Atlassian account credentials.
• For paid-feature checks, installations or upgrades representing active or trial and inactive license states.

Requested permissions

1. Install and open settings

1. Install or upgrade the submitted version and approve its permissions.
2. As the Jira administrator, open Apps → Manage your apps → VersionSelect for Jira settings → Configure.
3. Confirm the page opens and shows Backend API, Manual configuration, Selection rules, and Diagnostics. No manual-catalog cleanup action should be exposed.
4. Sign in as the non-administrator and attempt to open the same configuration entry. Jira should hide or deny its administrator-only module.

2. Configure and verify a manual catalog

1. Select Manual configuration. Add an ungrouped service and a grouped service, with at least two versions each. Rename one entry, use the up/down controls, and confirm duplicate service or version names in the same scope are rejected.
2. Set Maximum entries to a value from 1 through 20, then save. Reload settings and confirm the source, rule, order, names, and groups persist without an API URL or credential.
3. Use Export JSON. Import the exported file into the draft, confirm the replacement summary, apply it, and save. Also verify that an invalid or oversized import is rejected without replacing the active catalog.
4. Switch to Backend API without saving, refresh, and confirm the active manual source did not change. Saved configurations for the two modes remain separate.

3. Exercise the Jira field

1. Add the global Service & Version field to the test project's Create, Edit, and View screens.
2. Create an issue. Search for a manual service, select a version, add another service/version pair, reorder the selected pairs, and save.
3. Reload the issue and confirm the formatter preserves the saved order, group labels, service names, and version names. Edit the value, remove one pair, save, and reload again.
4. Open the editor, change the selection, and cancel. Reopen it and confirm the last saved Jira value is unchanged. Clear the field and save to verify an empty value is accepted unless Jira itself marks the field required.
5. Lower Maximum entries and confirm the picker prevents an additional service while still allowing version replacement and removal. At 20 entries, a 21-pair value submitted through a Jira-supported path must be rejected by the manifest validation.

4. Verify snapshots and JQL

1. Save a value, then rename or remove its source catalog entry. The existing issue must continue to display the saved name snapshot; removed entries must not reappear in new searches.
2. Search Jira with the aliases appropriate to the saved value: serviceId, serviceName, versionId, and versionName. Confirm the issue is returned for matching values and excluded for non-matching values.
3. Switch catalog sources and return to the issue. Previously saved Jira values must remain readable; VersionSelect does not bulk-rewrite issue fields when a catalog changes.

5. Connect the review catalog API

1. As the administrator, select Backend API. Enter the HTTPS base URL and credential supplied privately, then select Save configuration.
2. Approve the exact origin in Atlassian's outbound-access dialog. If practical, first deny the prompt and confirm the new configuration is not saved, then retry and approve it.
3. Select Test connection. A successful test must make a direct, uncached protected service-list request using an empty query, page 1, and page size 1. A public health endpoint is not sufficient to validate the credential. Open a field and confirm services and versions load from the supplied synthetic catalog.
4. Verify search and pagination, including two services with the same name in different groups where present. Default version results should show the latest ten; an explicit search can locate older versions.
5. Save a non-empty but invalid or unauthorized credential and select Test connection. A 401 or 403 response from the protected service-list request must be shown as AUTHENTICATION_FAILED without exposing response bodies or secret material. Deleting the token is a separate scenario: it disables connection testing and sends no external request. Use an invalid HTTPS route, if supplied in the private review notes, to confirm malformed or unavailable responses produce a safe error and do not fall back to removed historical options.

All external requests originate from Forge, use HTTPS, and follow the fixed contract in the API integration guide. VersionSelect sends catalog search and pagination data, not issue bodies, comments, attachments, or the Jira user's identity.

6. Verify licensing

For Forge development or staging verification, install or upgrade with the corresponding test-license option. Marketplace production licensing is provided through Paid via Atlassian with Standard billing.

7. Automatic maintenance, deletion, and retention

Manual catalogs use immutable rows. A save can replace an active row while leaving its unreferenced predecessor in Forge storage. VersionSelect handles these internal records through bounded daily background maintenance; there is no user-facing cleanup workflow or revision-restoration feature.

1. Change and save a manual catalog. Recent rows and valid drafts are intentionally protected for at least 24 hours, so immediate deletion is neither expected nor required.
2. Confirm settings remain usable and contain no cleanup preview, confirmation, cancellation, or progress controls. Saving configuration must not wait for background maintenance.
3. If private test-environment storage or developer-log evidence is available, verify a later daily run removes only eligible unreferenced manual rows, indexes, and expired sessions while preserving the active catalog and valid drafts. This maintenance never rewrites saved Jira issue values.
4. Delete the saved API credential from settings and revoke it at its source. Confirm settings report no stored credential.
5. Review Data deletion and retention for the boundary between automatic maintenance, Jira field values and history, external API records, downloaded exports, and support records.

Evidence checklist

• Installed app version, Jira site type, project type, account role, and license state used for each scenario.
• Screenshots of successful manual and API selections, saved/reloaded field rendering, the outbound-access approval, and expected safe errors.
• JQL queries and matching issue keys, with no customer data or reusable credential included.
• Confirmation that settings expose no cleanup workflow; include private storage or developer-log evidence for automatic maintenance only when available.
• For any failure: timestamp, step number, visible error code, and whether retrying changed the result. Send this through the Marketplace review ticket or support@fogsea.top.

Known boundaries

• The app supports Jira Cloud only and provides one global app-managed object field.
• The configurable catalog integration accepts only the documented HTTPS read contract; it is not a general REST mapping tool.
• A picker rule below 20 is enforced by the app UI. The manifest independently enforces the hard limit of 20 for Jira-supported writes.
• Changing or deleting catalog entries does not rewrite existing Jira issue values or Jira history.
• Customer-managed egress means the app is not eligible for the Runs on Atlassian badge.