Configuring and Indexing an Atlassian Jira Software V2 Source

A source defines a set of configuration parameters for a specific Jira Software instance.

To configure and index a Jira Software V2 source

1. On the Coveo server, access the Administration Tool (see Opening the Administration Tool).

2. Select Index > Sources and Collections.

3. In the Collections section:

   1. Select an existing collection in which you want to add the new source.

      OR

   2. Click Add to create a new collection (see Adding a Collection).

4. In the Sources section, click Add.

   The Add Source page that appears is organized in three sections.

5. In the General Settings section of the Add Source page:

   

   1. Enter the appropriate value for the following required parameters:

      Name

      A descriptive name of your choice for the connector source.

      Example: Jira V2

      Source Type

      The connector used by this source. In this case, select Jira v2.

      Note: If you do not see Jira v2 in the Source Type list, ensure that your environment meets the requirements (see Atlassian Jira V2 Connector Requirements).

      Addresses

      Enter the base URL of your Jira Software server.

      Example: http://MyJiraServer:8080/

      Fields

      Select the field set that you created earlier (see Atlassian Jira Software V2 Connector Deployment Overview).

   2. The following parameters often do not need to be changed:

      Rating

      Change this value only when you want to globally change the rating associated with all items in this source relative to the rating of other sources (see Understanding Search Results Ranking).

      Example: When the source indexes a legacy repository, you may want to set this parameter to Low, so that in the search interface, results from this source appear lower in the list compared to those from active repository sources.

      Document Types

      If you defined a custom document type set for this source, select it (see What Are Document Type Sets?).

      Active Languages

      If you defined custom active language sets, ensure to select the most appropriate for this source (see Adding and Configuring a Language Set).

      Refresh Schedule

      Time interval at which the index is automatically refreshed to keep the index content up-to-date. By default, the Every day option instructs CES to refresh the source everyday at 12 AM (see Creating or Modifying a Source Schedule).

      Live monitoring with a Jira webhook efficiently and continuously maintains your source up to date. The full refresh is a safety net to ensure all modifications are taken into account.

      Example: If your Coveo Master Server is down for maintenance for an hour and the Jira webhook pushes changes during that time, they will only be taken into account in the index on the next full refresh.

6. In the Specific Connector Parameters & Options section of the Add Source page:

   

   1. In the Mapping File box, the path to the default mapping file that defines how the connector handles metadata often does not need to be changed.

   2. Review if you need to change the default values for the following parameters:

      Support Comment Permissions

      By default, this check box is cleared so the issue and its comments are indexed as one document, allowing to find a document from either an issue or its comments. However, there are no restrictions on users seeing comments on an issue.

      Select the check box, to respect the permissions on the comments, so that only users allowed to see a comment in Jira Software can also see it in search results. In this case, an issue and its comments are indexed in separate documents leading to lower search relevance.

      Index Attachments

      When selected, CES indexes binary files attached to an issue. Attachments are indexed with the same level and sets of their parent issue.

      Index Comments

      When selected, CES indexes comments on issues. Comments are indexed with the same level and sets of their parent issue. When permissions on the comments are supported, if a comment is restricted to a group or a project role, an additional set with the group or the role is added.

      Index Work Logs

      When selected, CES indexes time entry on an issue. Work logs are indexed with the same level and sets of their parent issue. If a work log is restricted to a group or a project role, an additional set with the group or the role is added.

   3. (Optional) In the Parameters section, click Add Parameter and then use the following hidden parameters when you want to use Kerberos authentication:

      

      UseKerberosAuthentication Security provider CES 7.0.7711+ (June 2015)

      Whether to use Kerberos authentication. The default value is false. Set it to true when crawling a Kerberos setup.

      ServicePrincipalNames Security provider CES 7.0.7711+ (June 2015)

      The custom server principal name (SPN) to use with the Kerberos authentication. The SPN is almost always in the following format: HTTP/server.name@server.domain. If the domain name is not contained in the SPN, the connector uses the user domain, which may be wrong. Use this parameter when the crawling user identity used is not on the same domain as the Jira Software server.

      Example: You use user@domain.com as the user identity to crawl http://jira.dev.domain.com.

      Notes:

      • This parameter is only used when the UseKerberosAuthentication parameter value is true.

      • Make sure the user identity exists in both Jira Software and AD.

      • When you get the following error:

        The Kerberos Authentication failed for user 'userIdentity' with the SPN 'HTTP/ServerName'.

        it means the user identity and/or the SPN are wrong.

   4. The Option check boxes generally do not need to be changed:

      Index Subfolders

      Keep this check box selected (recommended). By doing so, all subfolders from the specified server address are indexed.

      Index the document's metadata

      When selected, CES indexes all the document metadata, even metadata that are not associated with a field. The orphan metadata are added to the body of the document so that they can be searched using free text queries.

      When cleared (default), only the values of system and custom fields that have the Free Text Queries attribute selected will be searchable without using a field query (see Adding a Field to Search On and What Are Field Queries and Free Text Queries?).

      Example: A document has two metadata:

      • LastEditedBy containing the value Hector Smith

      • Department containing the value RH

      In CES, the custom field CorpDepartment is bound to the metadata Department and its Free Text Queries attribute is selected.

      When the Index the document's metadata option is cleared, searching for RH returns the document because a field is indexing this value. Searching for hector does not return the document because no field is indexing this value.

      When the Index the document's metadata option is selected, searching for hector also returns the document because CES indexed orphan metadata.

      Document's addresses are case-sensitive

      Leave the check box cleared. This parameter needs to be checked only in rare cases for systems in which distinct documents may have the same name but different casing.

      Generate a cached HTML version of indexed documents

      When you select this check box (recommended), at indexing time, CES creates HTML versions of indexed documents. In the search interfaces, users can then more rapidly review the content by clicking the Quick View link rather than opening the original document with the original application. Consider clearing this check box only when you do not want to use Quick View links or to save resources when building the source.

      Open results with cached version

      Leave this check box cleared (recommended) so that in the search interfaces, the main search result link opens the original document with the original application. Consider selecting this check box only when you do not want users to be able to open the original document but only see the HTML version of the document as a Quick View. In this case, you must also select Generate a cached HTML version of indexed documents.

7. In the Security section of the Add Source page:

   

   1. In the Authentication drop-down list, select the Jira Software V2 crawling user identity that you created for this source (see Atlassian Jira Software V2 Connector Deployment Overview).

   2. In the Security Provider drop-down list, if you chose to index permissions, select the Jira Software V2 security provider that you created for this source (see Configuring an Atlassian Jira Software V2 Security Provider). Otherwise, select None.

   3. Click Save to save the source configuration.

8. In the case your Jira content is all public and you chose to not index Jira permissions: 

   

   1. In the navigation menu on the left, select Permissions.

   2. Next to Permissions, select the Specifies the security permissions to index option.

   3. Next to Allowed Users, ensure that a well-known everyone group such as the Active Directory everyone \S-1-1-0\ is added.

   4. Click Apply Changes.

9. On the toolbar, click Rebuild to start indexing your source.

10. Validate that the source building process is executed without errors:

    • In the navigation panel on the left, click Status, and then validate that the indexing proceeds without errors.

      OR

    • Open the CES Console to monitor the source building activities (see Using the CES Console).