> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Jira > Configure Jira issue indexing for Cloud or Server/Data Center with explicit content and permission boundaries. ## What it indexes The Jira connector turns each matching issue into one searchable document. It can index every issue visible to the credential, one project selected by project key, or issues matched by a custom JQL query. OpenCore adds its own `updated` time window to every indexing query. | Issue data | Indexing behavior | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Content | The issue description and comments are combined into one text section. A comment is omitted only when Jira returns `comment.author.emailAddress` and it is a case-sensitive exact match for a **Comment Email Blacklist** entry. If the email is absent, the comment remains indexed. | | Metadata and hierarchy | The key, summary, project, type, status, priority, resolution, labels, dates, reporter, assignee, and parent are retained when available. Projects and epics appear as hierarchy nodes. | | Attachments | Attachment files and their extracted text are not fetched by this connector. | | Filters and limits | A deployment-level label list can skip issues. An issue whose combined description and comments exceed the deployment's ticket-size limit is skipped; the current default limit is 100 KiB. | Do not add `updated` or other time-based filters to custom JQL, and do not add an `ORDER BY` clause. Those expressions conflict with the connector's polling and pagination logic. ## Prerequisites * Identify the Jira site Base URL, such as `https://.atlassian.net` for Jira Cloud or the root URL of Jira Server/Data Center. * For Jira Cloud, create an API token for a user that can browse every project and issue in scope. Keep that user's email available. * For Jira Server or Data Center, create a Personal Access Token for a user with the required browse access. * If using a scoped Jira Cloud token, keep the normal site Base URL and enable **Using scoped token** in the connector form. OpenCore resolves the site's Cloud ID and sends API requests through Atlassian's scoped API host. * For **Auto Sync Permissions**, the token also needs access to project permission schemes, project roles, users, groups, and group membership. ## Credentials | Jira deployment | OpenCore credential values | Authentication behavior | | ---------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Jira Cloud | `jira_user_email: `, `jira_api_token: ` | When the email field is present, OpenCore uses email-and-token basic authentication with Jira REST API v3. | | Jira Cloud with scoped token | `jira_user_email: `, `jira_api_token: ` | Use the Cloud credential fields and also enable **Using scoped token** on the connector. | | Jira Server or Data Center | `jira_api_token: ` | Leave **Jira User Email** blank. OpenCore omits that field and uses token authentication with Jira REST API v2. | The Base URL and scope settings belong to the connector, not the credential. Do not paste a project URL into the Base URL field. ## Configure in OpenCore 1. In the Admin panel, open **Connectors**, select **Jira**, and create the credential for your Jira deployment. 2. Enter the Jira root **Base URL**. OpenCore removes a trailing slash before building API and issue links. 3. Enable **Using scoped token** only for a scoped Jira Cloud token. 4. Under **How Should We Index Your Jira?**, choose **Everything**, **Project**, or **JQL Query**. For **Project**, enter only the project key. For **JQL Query**, omit time filters and `ORDER BY`. 5. Optionally add comment-author email addresses to **Comment Email Blacklist**. Matching is case-sensitive and exact, depends on Jira returning `comment.author.emailAddress`, and is not a reliable privacy boundary. Verify each intended author after indexing. 6. Choose the document-access mode, set refresh and cleanup options, create the connector, and run the first indexing attempt. ## Permissions The credential determines which issues OpenCore can retrieve. Without **Auto Sync Permissions**, Jira access is not re-evaluated when a user searches: use OpenCore **Private** groups for restricted content, or **Public** only when every OpenCore account may search every indexed issue. When **Auto Sync Permissions** is available and selected, OpenCore reads each project's `BROWSE_PROJECTS` permission scheme and applies the resolved project access to every issue from that project. It recognizes `anyone`, direct users and groups, and actors in project roles. Jira groups and their member emails are synchronized separately. applicationRole is currently treated as OpenCore Public as soon as that holder type is present. OpenCore does not synchronize the licensed Jira users behind that role, so every OpenCore account may search the project's indexed issues, including accounts without a Jira license. If that is too broad, do not use Auto Sync for the connector; choose OpenCore **Private** groups and narrow the project or JQL scope instead. This is project-level static permission resolution. The connector does not independently evaluate issue security levels, and dynamic holders such as reporter or assignee are not converted into per-issue ACLs. Unsupported or dynamic-only holders can resolve to empty private access. Test representative restricted projects before relying on synchronized access. ## Verify 1. Validate the credential. For **Everything**, validation lists projects; for **Project**, it opens that project; for custom JQL, it executes a limited search. 2. Run an indexing attempt and search for one issue description and one comment in scope. 3. Confirm an issue outside the selected project or custom JQL is absent. 4. Use a target comment whose Jira API response exposes `comment.author.emailAddress` with the same case as the configured entry, then confirm that comment is absent. Also test a case mismatch or an author without a returned email and confirm the comment remains indexed. Confirm attachment-only text is not searchable. 5. Open a result link and confirm it uses the configured Base URL and `/browse/`. 6. If using **Auto Sync Permissions**, test `anyone`, `applicationRole`, directly assigned, group-assigned, project-role, and issue-security cases. For `applicationRole`, include an OpenCore account without a Jira license and confirm whether the Public mapping is acceptable. ## Troubleshooting | Symptom | What to check | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validation returns 401 | Replace an expired or invalid API token or Personal Access Token, and confirm the Cloud email matches the token owner. | | Validation returns 403 | Grant the credential browse access for the selected project or JQL. Permission sync requires additional access to schemes, roles, users, and groups. | | Project validation says the project does not exist | Check the exact project key and confirm the credential can see it. | | Custom JQL is rejected or polling misses issues | Remove time-based predicates and `ORDER BY`; OpenCore adds its own `updated` range. | | A targeted comment remains despite the blacklist | Confirm Jira returned `comment.author.emailAddress` and that it is a case-sensitive exact match. Missing emails and case differences do not filter the comment; use OpenCore access controls and connector scope rather than this field as a privacy boundary. | | An issue is missing | Check the project or JQL scope, deployment label-skip configuration, the ticket-size limit, and issue browse permission. | | Attachment text is missing | This is expected; the Jira connector does not fetch attachments. | | Auto Sync access is too broad or too narrow | An `applicationRole` holder makes the project Public to all OpenCore accounts, including accounts without a Jira license. Issue security and dynamic holders are not resolved as per-issue ACLs. If either mapping is unsuitable, use **Private** groups and a narrower connector scope instead of Auto Sync. | | Validation reports rate limiting | Wait for the Jira limit window to recover, then validate or index again. | ## Related pages * [Connectors & Indexing](/opencore/knowledge/connectors) * [Index Settings](/opencore/knowledge/index-settings)