Jira connector for Simpplr Enterprise Search

Table of Contents

Overview

Prerequisites

Authentication and security

Setup and configuration

Field mapping and search experience

Monitoring and troubleshooting

FAQ

Overview

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

With this connector, you can:

• Bring Jira content into Simpplr Enterprise Search so users can find Jira’s projects and issues , with attachments  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:

• 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
• Attachments 

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

• Jira user and group memberships are fetched and stored in the ACL index.
• When a user is added to or removed from a Jira group, the ACL index is updated the next time the ACL sync runs (by default, every hour).

2. How public or link-shared content is handled

• Content that is only available via anonymous or public shared links is not indexed in the current version.

3. 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 ACL sync.
• The file will no longer appear in that user’s Simpplr search results after the ACL sync completes.

Versions and editions supported 

• Supported Jira account editions: All.
• Not supported: N/A 

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: Indexed content and ACLs 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: Jita 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

Step 1 - Prepare Jira source

Connector Authentication 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 a Product Admin.

•  Navigate to Security > API Tokens > Create and Manage API Tokens.

•  Generate and copy the API Token.

Step 2 - Create the connector in Simpplr

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 
   • Jira Cloud token
   • Jira Host url

5. Click Save and Confirm. 

Step 3 - Define sync scope

• 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 4 - Configure sync schedule

• Default schedule: Full crawl at first setup and once in a week, incremental sync every 4 hours, ACL runs every hour.
• Configuration options:
  • No option to configure the sync schedule, however sync can be paused and resumed manually.

Step 5 - Monitor the sync

1. Monitor the initial full sync status (starts automatically) in the connector dashboard.
2. Screenshot

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
• How long it may take: Depends on 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 4 hours and ACL sync every hour), changes made to Jira content are generally reflected in Simpplr search results within 4 hours of the update, and the permission lag in the system can be up to 4 hours. (as the incremental Sync every 4 hours). On top of that, there can be certain cases, where the permission sync can take up to 7 days (when the full sync is run), 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
   2. Resolution:
      1. Verify and re-enter credentials

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. This functionality has not been implemented yet.

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 4 hours and ACL (permission) sync runs every hour by default.

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. Does the connector index content from external guests or shared links?
A. Not implemented yet.

Q5. 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.

Though the access control syncs run every hour, the permission lag in the system can be up to 4hours. (As the incremental sync every 4 hours). On top of that, there can be certain cases, where the permission sync can take up to 7 days (when the full sync is run).

Q6. Can I exclude certain sites/teams/folders from being indexed?
A. Documents can only be excluded based on file extension, size, and age. Additionally, documents can be included or excluded based on audiences.

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