Jira Cloud — Story Agent

The Aprity Story Agent for Jira adds an AI-powered backlog panel directly inside Jira Cloud. It analyzes your Salesforce org's business rules, dependencies, and processes to generate structured user stories with acceptance criteria, impact analysis, and complexity estimates, then exports them as Jira issues.

info

The Jira integration rides on the Story Agent, which is available on the Intelligence and Trial plans (not on Documentation).

Your Jira site is connected through its base URL, which is validated against an allowlist (*.atlassian.net).

Prerequisites

Before you begin, make sure you have:

• A Jira Cloud instance (Server and Data Center are not supported).
• Jira administrator permissions to install Forge apps.
• An active aprity account with a connected Salesforce org (at least one completed scan).
• Access to the Connectors tab in the aprity Salesforce app.

Step 1 — Install the Forge app in Jira

1. Go to the Atlassian Marketplace and search for Aprity Story Agent.
2. Click Get app and select the Jira Cloud site where you want to install it.
3. Review the requested permissions and click Install.

The app requests the following permissions:

Permission	Purpose
read:jira-work	Read backlog items, epics, and project context
write:jira-work	Create and update user stories from generated content

Once installed, you will see Aprity Story Agent as a panel in your backlog view and Aprity Configuration in your Jira project settings.

tip

If you don't see the app after installation, ask your Jira admin to verify that the Forge app is enabled for your project.

Step 2 — Generate an activation code in Salesforce

The activation code links your Jira site to your aprity tenant. It is generated from Salesforce.

1. Open Salesforce and navigate to the aprity app.
2. Go to the Connectors tab.
3. Locate the Jira Cloud card and click Connect Jira (or Generate New Code).
4. A code in the format APRT-XXXX-XXXX appears. It expires in 30 minutes and can only be used once.
5. Copy the code using the Copy Code button.

caution

The code expires after 30 minutes. If it expires before you use it, click Generate New Code to get a fresh one.

Step 3 — Open the Aprity Configuration page

The configuration page lives in your project (or space) settings.

In the classic Jira UI

1. Open your Jira project.
2. Click the gear icon at the bottom of the project sidebar, or click Project settings.
3. In the settings list, scroll to the Apps section and click Aprity Configuration.

In the new Jira UI (Spaces)

If your Jira workspace uses the new Spaces experience, the path is slightly different:

1. Open your space (e.g., TeamAprity).
2. Click the "..." menu next to the space name, then choose Space settings.
3. In the settings sidebar, expand the Apps section and click Aprity Configuration.

Shortcut (any UI)

You can also navigate directly by URL. Replace <site> with your Jira site and <KEY> with your project key:

https://<site>.atlassian.net/jira/software/projects/<KEY>/settings/apps

Example: https://aprity-team.atlassian.net/jira/software/projects/SCRUM/settings/apps

tip

If you don't see Aprity Configuration in the Apps section, make sure the Forge app is installed and you have administrator permissions on the project/space.

Step 4 — Paste the activation code

On the Aprity Configuration page:

1. You will see a card titled Aprity Configuration with an input field for the activation code.
2. Paste the code (APRT-XXXX-XXXX) that you generated in Step 2.
3. Click Connect.
4. If the code is valid, the view switches to Connected to Aprity with a green checkmark.

Step 5 — Verify the connection

Once connected:

1. Open any project in Jira.
2. In the project tab bar, click the Aprity Story Agent tab (it has a DEV badge while in development mode).
3. The Story Agent panel should load with an input field asking you to "Describe your Salesforce change".

If the Story Agent panel still shows the setup card asking you to configure the app, reload the page (Ctrl/Cmd + Shift + R).

If the panel shows an error, verify that:

• Your aprity org has at least one completed scan.
• The activation code was used for the correct Jira site.

Using the Story Agent

With the connection active, you can:

• Generate user stories — describe what you need in natural language, and the Story Agent creates structured stories based on your org's actual metadata and business rules.
• Get impact analysis — each generated story includes which Salesforce objects, flows, and triggers are affected.
• Export to your backlog — push the generated EPIC / FEATURE / USER STORY hierarchy directly into your Jira backlog as issues. The export is idempotent: re-running it updates the existing issues rather than creating duplicates. This is a push to Jira, not a downloadable documentation file.

note

The Story Agent runs on aprity's deterministic knowledge tools, which read directly from your latest scan index. Its output is grounded in your org's real metadata, so it does not invent object names or field references.

Disconnecting

To disconnect Jira from aprity:

1. Open Aprity Configuration in your Jira project settings.
2. Click Disconnect.
3. Confirm the action in the dialog.

After disconnecting, the Story Agent panel will no longer load. You will need a new activation code to reconnect.

Troubleshooting

Issue	Solution
"Invalid code" error	Verify the code format is APRT-XXXX-XXXX. Codes are case-insensitive.
"Code expired" error	Generate a new code from the aprity Connectors tab in Salesforce.
Panel not visible	Check that the app is installed and enabled for your project (Jira admin > Manage apps).
"No scan data" in panel	Run at least one scan from the aprity app before using the Story Agent.
Connection lost after some time	The integration credentials do not expire, but if your aprity subscription lapses the panel will show an error.