Integrations

Jira integration

Connect Jira Cloud, select projects, and use issue evidence in documentation requests and scheduled workflows.

Jira integration

Connect Jira to research product changes and find documentation that needs updating. Pageloop can read issues in selected projects, compare the evidence with your knowledge base, and prepare proposals for review.

Jira supplies source material; it is not a destination for publishing articles. Connect a knowledge base before using issue evidence to maintain documentation.

Before you begin

  • Sign in to Pageloop as an Admin to connect or configure Jira. Editors and Contributors can view integrations but cannot change them.
  • Use an Atlassian account that can authorize Pageloop and access the Jira Cloud site and projects you want it to read. Pageloop connects the first Jira Cloud site that account can reach; there is no site chooser. If the account can reach several sites, use an account that reaches only the site you want.
  • Choose at least one project containing work relevant to your readers.

The connection uses Jira Cloud authorization. These steps do not describe a Jira Server or Data Center connection.

Connect and configure Jira

  1. Open Integrations from the sidebar, or Settings → Workspace → Integrations.

  2. Find Jira under Project management and select Connect. You can use Search integrations to find the card.

  3. On Atlassian's authorization screen, review the site access and requested permissions, then authorize the connection.

  4. Back in Pageloop, a Connecting Integration page appears, followed by the Integration connected toast. Configure Jira Projects opens automatically when no projects are saved yet. The dialog says “Select the Jira projects to sync issues from.”

    Until you save projects, the Jira card shows Finish setup, not Connected. If you close the dialog before saving, select Finish setup to reopen it. A connection without saved projects is not watched.

  5. Under Select projects to sync issues from, search and tick one or more projects, such as <your project>. Selected projects appear as their keys, with a count below: N projects selected. Save Configuration stays disabled until you select at least one project.

  6. Select Save Configuration. The Configuration saved toast confirms “Successfully configured N Jira project(s)”, where N is the number of selected projects.

  7. Check that the Jira card reads Connected. Select its gear button (Configure) to confirm the saved projects or change them later.

Separate Jira app for mentions

Install the Jira app after connecting Jira. If the app is not installed, the Pageloop Jira App box in Configure Jira Projects says “Install our Jira app to enable @Pageloop mentions in issue comments.” Select Install Pageloop Jira App to install it. This is a separate installation from the OAuth connection used for reading issues. The app enables @Pageloop mentions in issue comments.

After installation, return to the configuration dialog. Pageloop refreshes the installation status when you return to the tab and shows Installed when it detects the app. The box says “The Pageloop Jira app is installed. You can reinstall if needed.” and offers Reinstall Pageloop Jira App. An installed app does not replace the Jira connection or project selection.

Permissions and what Pageloop can read

The Jira connection requests these OAuth permissions:

PermissionPurpose
read:jira-workRead Jira work information for issue research.
read:jira-userRead user information exposed with Jira records.
offline_accessRefresh authorization so scheduled research can continue without a fresh interactive sign-in for each run.

These are the OAuth connection's permissions, not the separate Jira app's installation permissions. Review the app's own consent screen if you install it.

Pageloop's documentation research tools are read-only. They search issues using Jira Query Language (JQL) and retrieve issue details; they do not use that research path to create, edit, assign, transition, or delete Jira issues.

InformationHow it supports documentation
Issue key, summary, description, and URLIdentify the change and the source for a proposed edit.
Status, resolution, type, priority, and update timeSelect relevant work and understand whether it is ready to document.
Labels, components, and fix versionsUnderstand the affected product area and any configured filters.
Available comments, author names, and timestampsRead clarifications and explanations beyond the original issue description.
Linked issue keys and relationshipsFind related work. A linked issue's full contents require a separate in-scope read.

Reads are restricted to the configured projects and any tracked label filter that applies to the connection. Pageloop checks that returned issues match that scope. Supplying a key or link from another project does not bypass the restriction or the access available to the connected Atlassian account.

The project picker does not offer a label-filter control. If a label restriction is already configured for your connection and an expected issue is missing, ask Pageloop to help check the integration's scope rather than assuming the project selection is the only filter.

Supported workflows

Research a specific change

Give Pageloop an issue key or link in a documentation request and explain the desired edit. For example: “Use these resolved export issues to check the export guide. Verify the permissions and limits before drafting changes.”

Pageloop can search for relevant issues and read the details of candidates. Providing the issue key is useful when broad text search would be ambiguous. The issue must be accessible and within the configured scope.

Request documentation from an issue comment

  1. Complete the Jira connection and project configuration above.
  2. In Configure Jira Projects, select Install Pageloop Jira App and complete the installation. Return to Pageloop and check for Installed.
  3. Open the relevant Jira issue and add a comment mentioning @Pageloop. Explain the documentation work you want, such as which behavior to document or which article to check.
  4. Pageloop looks into the issue and replies with a comment on it. The reply either lists articles it suggests adding or updating, ending with “… suggestion(s) total. Review them on Pageloop.”, or says it found no documentation updates needed.
  5. Review the results in Pageloop before publishing.

The issue and initiating comment provide context for the request. This direct request is separate from a scheduled check and is supported for both Pageloop Docs sites and connected help centers.

Review Jira activity on a schedule

For a Pageloop-hosted knowledge base, saving the project configuration creates a draft workflow named Keep docs in sync with Jira in Workflows. The draft is scheduled daily at 09:00 in your time zone, but does nothing until activated. Open Workflows to activate or edit it. In the steps, specify which issue states indicate work you want documented, which product areas matter, and what the agent should produce. See Create and manage workflows for testing, activation, and run history.

Scheduled runs review issues updated during their time window. When the steps do not name a status, the Jira workflow guidance considers resolved issues and skips issues closed as won't do or duplicate. Use your own workflow steps to explain what your team's statuses mean; a status name alone may not prove the product change is available to readers.

Checks run periodically according to the workflow, not immediately for every issue change. A scheduled check starts only when issues in the selected projects have changed since the last run; otherwise, it is skipped with Nothing new since the last run. Connecting Jira alone does not guarantee an immediate suggestion.

If Jira access is lost, runs fail with Jira is disconnected, and the workflow shows The source is disconnected - reconnect it in Integrations. Three failed runs in a row pause the workflow with Paused after three failed runs in a row.

What happens after research

Pageloop checks existing articles before deciding whether to update a page or draft a separate topic. Several issues can support one proposal, and issues already covered by the documentation may produce no change.

Results appear in Pageloop for review, with supporting source references where available. Review the evidence and draft before publishing. The run can ask questions when an important detail is not established by the issues. Automatic research and drafting do not publish the result.

Disconnect Jira

  1. Point at Connected on the Jira card; it changes to Disconnect. Select it.
  2. Review Disconnect Jira?. The dialog explains: “Pageloop stops reading from and writing to it.”
  3. Select Disconnect to confirm, or Keep connected to cancel.

The Jira disconnected toast confirms the disconnection. The Pageloop Jira app stays installed in Jira; a Jira admin must uninstall it there. The draft workflow stays in Workflows. If activated while Jira is disconnected, its runs fail with Jira is disconnected until Jira is connected again.

Reconnect Jira

When Atlassian stops accepting Pageloop's access, the Jira card shows Needs reconnecting. The page says “Jira needs to be reconnected. Pageloop lost access, so it is paused until you reconnect it.” Select Reconnect Jira and approve access again.

Limitations and troubleshooting

SymptomWhat to check
No Jira sites accessible with this accountThe Atlassian account has no Jira Cloud site. Use another account.
Error connecting integration with Invalid state parameterThe connection finished in another tab or browser. Start again from Connect.
Error loading projects (for example, Failed to load Jira projects)Pageloop could not load the project list. Try again; if it persists, reconnect Jira.
Configuration failedThe save did not go through, and the dialog stays open. Try again.
Please select at least one projectTick a project before saving.
Save Configuration is disabled.Wait for projects to load and select at least one project.
The expected project is missing.Check the connected Jira Cloud site and the authorizing account's project access. Search by both project name and key.
Jira appears as Not connected in a workflow despite authorization.Complete project configuration in Integrations. A workflow needs an active connection with projects selected.
An issue cannot be found by key.Confirm the key, selected project, connected account's access, and any configured label restriction. Linked issues are also subject to scope checks.
The Jira app does not show Installed.Return to the configuration tab after installation and check the status. Installing the app and connecting Jira are separate steps.
Needs reconnectingSelect Reconnect Jira and approve access again.
Jira is disconnected or The source is disconnected - reconnect it in IntegrationsAsk an Admin to reconnect Jira in Integrations. A revoked or unrefreshable connection remains unavailable for the rest of that run; retry the work after restoring access.
Paused after three failed runs in a rowCheck the run history and restore Jira access if it was lost before activating the workflow again.
Nothing new since the last runNo issues in the selected projects changed since the last run, so the scheduled check was skipped.
A search or issue read is incomplete.Large result sets and long descriptions or comment histories can be limited. Give the agent a narrower time window, project, status, or list of issue keys. Do not assume every linked resource, comment, or attachment was read.
There are no suggestions.Check saved projects, an active workflow, its schedule, and run history. Relevant resolved work may already be documented or may not affect readers.