Jira connector for Simpplr Enterprise Search

Overview

The Jira connector allows Simpplr Enterprise Search to index Jira Projects, Issues (Task, Bug, Sub-task, Enhancement, Story) that you have created in Jira, making it easily discoverable and searchable directly within Simpplr.

With this connector, you can (use cases):

• Bring Jira content into Simpplr Enterprise Search so users can find Jira’s projects and issues, alongside intranet content in one place.

• Respect Jira permissions so users only see files they already have access to in Jira.

• Use advanced features like autocomplete, hybrid ranking, and Smart Answers on top of Jira content.

Indexed content from Simpplr Enterprise Search is available in:

• In main search listing

• Smart answers

Capabilities at a glance

Objects and content supported

1. Objects - List the object types that are indexed, for example:

• Projects

• Issues

2. Metadata - For each indexed item, Jira captures based on the type of Object: 

• Description 

• Project key

• Project type

• Lead name

• Created time 

• Last modified time

• File type

• Issue type

• Parent issue details

• Fix versions

• Affected versions 

• Resolution

• Attachments

• Comments 

• Sub-task details

• Priority

• Custom fields

• Size

• Mime type

• Permissions

3. Permissions model - Permissions are read from Jira and enforced in Simpplr Enterprise Search. Include: 

   1. How user and group permissions are synchronized

      1. Jira user and group memberships are fetched and stored in the ACL index.

      2. When a user is added to or removed from a Jira group, the ACL index is updated in the next sync cycle.

4. What happens when access is removed for a specific document

• When a user loses access to a Project or Issue in Jira, the updated permissions are applied during the next sync cycle.

• The file will no longer appear in that user's Simpplr search results after the sync cycle completes.

Versions and editions supported 

• Supported Jira account editions: Jira cloud.

• Not supported: Jira Server and Jira Datacenter

Prerequisites

Before you begin, ensure the following:

1. Source system permissions

• You need access to the Jira cloud Developer Console to create and configure your application

2. Application/service account

• The user should be having Product Admin access (to Sync Access Control Information)

• Ability to generate API token from Security section of the above user’s profile 

Jira documentation

• Jira Admin

• List Projects

• List Issues

Authentication and security

Authentication mechanism

Describe how Simpplr Enterprise Search connects to {{SourceSystem}}:

• Auth type: Api token (Client credentials)

• Scopes or permissions required (examples):

  • User needs to have Product Admin access

Data security

1. Data storage and residency: Data indexed from Jira are stored within your Simpplr Enterprise Search environment, in the same region as your Simpplr tenant.

2. Encryption in transit: Server-side encryption with Amazon S3 managed keys (SSE-S3), TLS encryption in Kafka.

3. Encryption at rest: SSL (TLS 1.2 or higher), Auth: OAuth 2.0 Bearer tokens (client-credential).

4. Permission enforcement: Jira access controls (users and groups) are stored in the ACL index and applied at query time. Search results are always filtered by the signed-in user’s identity and Jira group memberships.

Setup and configuration

There are two steps to setup this connector:

1. Setup credentials in Jira Source - This step yields an Api Token that will be used in the next step.

   • Type of Tokens

     1. Classic (General Access)

     2. Scoped Access

2. Setup the connector in Simpplr Intranet

Step 1 - Prepare Jira source

Step 1a - Setup Prerequisites

• Log in to Jira Cloud using the Admin Account.

• Make sure the user has Product Admin access. (Required to sync Access Control related information)

• Here are the steps to add Product Admin access for a new user or if the user does not have Product Admin access:

  • Go to Jira Administration by clicking the tiles on the Top Left of the Screen

1. Go to Directory and click on the User.

2. Under Product Access, click on Grant access and add Product Admin

Step 1b - Configuring the Api Token

•  Navigate to Security → API Tokens 
  There are two token options available:The Jira Connector supports both Scoped Tokens and General Tokens. You may choose either type based on your access requirements.

  • Scoped Token:
    Scoped API tokens allow you to specify what actions a token can perform in Confluence Cloud. Unlike classic tokens, which grant all permissions available to the user, scoped tokens restrict access to only the selected scopes, reducing risk if a token is compromised.
    Scoped tokens have specific permissions and are restricted by selected scopes. They use the api.atlassian.com domain instead of your site-specific URL.

• General Token (Classic):
  Classic tokens often grant all permissions available to the user who generated them across an entire account or organization. For example, a classic token with "repo" scope has access to all private repositories the user can access.

Due to their broad access, Classic tokens pose a greater security risk if compromised. Revealing a classic token could potentially expose all of an organization's projects and data.

Scoped Api Token

1. Select Create API token with scopes.

2. Give your API token a name that describes its purpose.

3. Select an expiration date for the API token.

• Token expiration must be between 1 and 365 days.

4. Select the Jira app for the API token to access.

5. Select the below mentioned scopes

   • read:account

   • read:jira-user

   • read:jira-work

   • read:me

   • read:servicedesk-request

6. Select Next, review the token and then select Create.

7. Select Copy to clipboard, then paste the token to your script, or save it somewhere safe.
   You can't recover the API token after you’ve completed this step. We recommend saving it in a password manager.      

Classic Api Token

Step 1c - Extracting the Jira Cloud ID

Cloud ID can be accessed by navigating to URL:

 <you-tenant-url>/_edge/tenant_info

For Example: If your JIRA application URL looks like this: https://simpplr.atlassian.net/jira/for-you, your tenant URL would be: https://simpplr.atlassian.net

Finally, your cloud ID can be accessed using this URL:
https://simpplr.atlassian.net/_edge/tenant_info

Step 1 Output

1. Api Token - Classic / Scoped

2. Jira Cloud ID

Step 2 - Create the connector in Enterprise Application

Step 2a - Setting up the configuration

1. In Simpplr, go to: Manage Features → Enterprise Search → Add Source.
   
   

2. Search and Select “Jira Cloud”.
   

3. Enter basic information:

   • Name: (Connector Name for this instance)

4. Provide authentication details:

   • Jira Cloud Service Account Id (email)

   • Jira Cloud token (copied from the earlier step)

   • Jira Host url: Host URL should be in the format (use the cloud Id from the earlier step)
     https://api.atlassian.com/ex/jira/<Cloud ID>

5. Click “Save” and “confirm”. 

Step 2b - Setting up the Data & Audience Filters

• Configure inclusion rules:

  • Not configurable in the current version

• Configure exclusion rules:

  • Not configurable in the current version

• Configure Audience based filtering.

  • Include audiences

  • Exclude audiences

Step 2c - Save & Sync

• Default schedule: Full crawl at first setup and once in a week, incremental sync every hour.

• Configuration options:

  • Sync can be paused and resumed manually

Step 2d - Monitor

1. Run the initial sync by clicking the start sync button. Monitor the latest sync status in the connector dashboard. This page shows the status of first full sync completed with latest full/incremental completed/failed status here.Crawling and sync behavior

How the connector works over time:

1.  Initial full crawl

• All the content present in the storage account is indexed during the first run

• It may take a while to complete the initial sync, depending upon the size of the content.

2. Incremental updates

• Mechanism: Based on Timestamp of previous sync.

• What changes trigger reindexing:

  • New items created

  • Existing items updated

  • Permissions changed

  • Items moved or renamed

  • Items deleted or archived

3. Deletion and permission changes

• Deleted items are removed from index at next sync.

• Permission changes are updated at the next sync cycle.

4. Expected latency: With the default schedule (incremental sync every hour), changes made to Jira content (such as new messages or channel updates) are generally reflected in Simpplr search results within a few hours of the update, subject to content volume and system load.

Field mapping and search experience

 Search experience - how content from this connector appears in search:

• Result layout: (Icon, Connector name, title (name) as link, body(excerpt), owner, Created Date, File Type icon, file type)

• Available filters and facets: 

  • Sources = Jira Cloud

  • File type

  • Owner

  • Created Date

• Participation in advanced features:

  • Smart Answers / Q&A: Yes

  • Autocomplete: Yes

  • Recommendations / “Suggested for you”: N/A

  • Trending / popular results: N/A

Semantic / hybrid ranking: Yes

Limits and known limitations

Monitoring and troubleshooting

1. Connector health and monitoring - Describe where admins can see status information:

• Enterprise Search > Connector name

• Available metrics:

  • Last sync status (Success/Warning/Failed)

  • Last sync time

  • Next scheduled sync

  • Sync type

  • Total items indexed count

2. Common issues and resolutions. Example pattern:

   1. Issue: Authentication failed, Failed to authorize with the given Api token (invalid credentials or missing scopes)
      Possible causes:

      1. Incorrect Token

      2. User does not have the access of Product Admin

      Resolution: Verify and re-enter credentials

   2. Issue: 404 error, URL not found

      Possible causes:

      1. could be Incorrect Host URL, Incorrect Cloud ID
         Resolution: Verify the cloud ID and Host URL Format.

Confirm if the user has the access of Product Admin.

When to contact Support

1. Authentication error persists even after trying the above-mentioned resolutions

2. Sync is stuck in the Pending state.

3. Sync is in progress but no documents are getting ingested.

4. Sync failure with cancelled error (when not cancelled manually)

5. Incomplete or partial sync.

When contacting Support, include:

• Connector name and instance ID (if available)

• Organization URL

• Approximate time and date of the issue

• Error messages or screenshots

• Steps you already tried

Frequently asked questions (FAQ)

Q1. Can I connect multiple Jira tenants or domains?
A. Multiple Jira connections can be configured in the Simpplr environment via multiple connectors.

Q2. How often does Jira sync data?
A. The connector runs a full crawl on first setup and then once per week. Incremental sync runs every hour.

Q3. Are comments, revisions, or version history indexed?
A. Comments and individual versions are not indexed as separate items. The connector indexes the latest file metadata, including the last updated time and updated-by user.

Q4. What happens when a user loses access to an item in Jira Storage ?
A. The updated access permissions will be indexed during the next sync cycle.

Note: Files and permissions are synced every hour. However, the actual update time may vary depending on the volume of data created within that period. Under normal conditions, changes are reflected within 1–2 hours, provided there has not been a significant spike in data uploads.

Q6. How are deletions handled?
A. Objects deleted from the source are permanently deleted from the index.

Q7. Are attachment files searchable ?
A. No, attachment objects are not searchable

Q8. Can I exclude certain sites/teams/folders from being indexed?
A. Documents in the search results can be filtered based on audiences.