Jira connector tutorial part I

In this article, we'll review a use case for the Elastic Jira native connector. We'll use a mock project where a bank is developing a money transfer app and needs to integrate the information in Jira into Elastic.

The native connector allows us to get into our Elastic cluster information from tickets, tasks, and other documents, centralizing data and enabling advanced search features.

The main benefits of using this connector are:

Data from Jira is synchronized with Elasticsearch.
Access to advanced search features.
Document Level Security (DLS) matching source security. You can only search for what you're allowed to see in Jira.

Steps

Configuring Jira connector

You'll first need to get an API token from Jira to connect to Elasticsearch. Go to this link to learn how to create it.

Name it "elastic-connector." It should look like this:

Get the token and to your Kibana dashboard. Then, go to native connectors and select New Jira Cloud connector.

Replace YOUR_KIBANA_URL with Kibana endpoint.

Name the connector “bank” and click “Create and attach an index named bank” to create a new index with the same name.

Done! Now we need to configure our Jira data.

We'll keep "Enable SSL" off since we won't be using our own SSL certificates.

You can see the details of each field in the official documentation.

Activate Document Level Security (DLS) so you get your documents with the users and groups authorized to see them.

Once the connector is correctly configured, you can continue to synchronize data as you can see below. It might take a couple of minutes to get the data from Jira.

Full Content: indexes all Jira documents.
Incremental Content: only indexes changes from the last Full Content Sync.
Access Control: indexes Jira users in the security index to activate DLS.

We can check the connector's Overview to see if the sync was successful.

In the Documents tab, we can see exactly what data we got with the connector. The objects from this first sync are:

Projects
Issues
Attachments

Indexing documents into Elasticsearch

We are not limited to searching across the connector documents. Elasticsearch allows you to search on many indices with a single query.

For our example, we'll index additional documents into the galactic_documents index to see how search works with more than one datasource:

Compliance Manual of the GBFF
User Guide for the Galactic Banking App
Technical Specifications Report

But before indexing, we'll create optimized mappings for each field:

With the mappings configured, we can now index:

Querying data

Now that we have both Jira objects and documents, we can search for them together.

Querying "galactic moon" will get us both Jira objects and the documents we indexed:

If a document is too long, you can add the option _source to the query to only include the fields that you need. If you just want to remove some fields, we'll cover that option in the second part of this series.

Document Level Security (DLS)

We will now configure Document Level Security (DLS) to match Jira permissions to the ones in Elasticsearch so that when users search, they can only see what they are allowed to see in Jira.

To begin, we'll go to the connector's Control Panel in Elastic Cloud and click on Access Control Sync.

Jira connector's Control Panel in Elastic Cloud

This sync will bring the access and permission info from the Jira users. To test this, I've made another Jira board to which the user "Gustavo" does not have access.

Note: Do not forget to run content sync after creating the board.You can run one time syncs, or schedule based.

Let's begin checking that the documents from the new board are there:

We can effectively see the issues:

However, since the user "Gustavo" does not have access, he should not be able to see them.

Let's look for the user's document in the ACL filter index to see their permissions.

Response:

This index includes the user id and all of their Jira groups. We need to make a match between the content in the user's access control and the field _allowed_access_control in each document.

We'll create an API Key for Gustavo using the command below. You must copy the query.template value from the previous step:

Note that we're only giving access to the indices in this article through this option.

The response for the creation of the API Key for Gustavo is this:

You can use curl to test that we can run searches using the API KEY and it won't bring info from the Marketing board, since Gustavo does not have access to it.

Response:

We can see that Gustavo did not get any info since he did not have access. Now, let's test with the documents from the board that he is allowed to see:

Response:

Conclusion

As you can see, integrating Elasticsearch with Jira has many benefits, like being able to get a unified search on all the projects you're working on as well as being able to run more advanced searches in more than one data source. The added DLS is a quick and easy way to guarantee that users will maintain the access they already had in the original sources.

Want to get Elastic certified? Find out when the next Elasticsearch Engineer training is running!

Elasticsearch is packed with new features to help you build the best search solutions for your use case. Dive into our sample notebooks to learn more, start a free cloud trial, or try Elastic on your local machine now.

Report an issue