Atlassian Jira

The JiraConnectorApi example solution showcases how to connect a Teneo solution with the Atlassian Jira REST API. The example flows in the solution demonstrate how tickets can be retrieved as well as how to create, assign, update or delete tickets in Jira.

jira

Solution contents

Jira integration

The solution contains a Jira backend integration containing methods for authentication, retrieval of tickets, users, issue types, filters and issue priorities. As well as for creating, assigning, updating, filtering and deleting tickets. Since the source code of the integration is embedded in the solution, it can be easily extended or used as a starting point for new methods.

Example flows

For each core method in the Jira integration, the solution contains a corresponding example flow:

User asks to retrieve the list of tickets assigned to someone
User asks to retrieve the list of tickets reported by someone
User asks to create a new JIRA ticket
User asks to assign a JIRA ticket to authenticated user
User asks to delete a JIRA ticket
User asks to update an existing field of JIRA ticket
User asks to filter tickets in JIRA
Bot asks a user to login into JIRA
User asks to logout from JIRA

Authentication flow

Jira provides a support for OAuth Authentication, API token-based authentication and basic authentication methods (deprecated) that allow a Teneo bot to interact with Jira on the user's behalf. Which authentication method to use depends on factors like use case and channel. This example solution contains flow to demonstrate API token-based authentication approach.

Getting started

Prerequisites

These instructions assume you have a Jira admin account. Alternatively, you can sign up for a free user account on Atlassian. These instructions assume you have downloaded and imported the JiraConnectorApi solution. See instructions below.

Create a Jira Project

It's time to create a project on Jira portal in order to perform and experience some CRUD operations by using JiraConnectorApi Teneo bot.

Using your administrator account, log in to your Jira portal.
Select the 'Jira Software' icon followed up by 'Create Project' button located on topmost right corner of portal.
Select the 'Select next-gen' button.
Enter a name of the project and key field would be populated automatically.
Finally select the 'Create' button. New Jira project setup is now completed.

Configure project settings (optional)

It's important to have a look on your project settings to manage the issue types and fields associated with each issue types.

On Jira portal, click on 'Project settings' is located at the bottom of left side menu.
Under 'Project settings' from left side menu, select Issue types to configure the issue fields associated with issue types more appropriately.
Click on various issue types such as Epic, Bug, Story, Task and Subtask check out fields under Context fields section.
For an instance, click on 'Priority' field from PREVIOUSLY-CREATED FIELDS and it will get added under Context fields section immediately.
Select the 'Save changes' button.
Repeat steps from 3 to 5 for other issue types.
From now on, Priority field can be editable via JiraConnectorApi Teneo bot.

Getting issue type id's specific to Jira project

It is mandatory to get the list of issue type ids from your Jira project instance and set it in JiraConnectorApi Teneo solution via a global variable called JiraConnectorApi_mIssueTypesMap for a bot to behave properly. The structure of this global variable looks like this:

JiraConnectorApi_mIssueTypesMap
['epic':'xxx','story':'xxx','bug':'xxx','task':'xxx','subtask':'xxx']

The result should look something like this: JiraConnectorApi_mIssueTypesMap ['epic':'10000','story':10001','bug':'10004','task':'10002','subtask':'10003']

Follow the steps below to get the list of issue type ids from your Jira project instance.

On Jira portal, click on 'Project settings' is located at the bottom of left side menu.
Select the 'Issue types' button.
Click on various issue types such as Epic, Bug, Story, Task and Subtask and store the values from the 'browser URL', which shows the id at the end.

The URL should look like this: https://[PROJECT_DOMAIN]/jira/software/projects/[PROJECT_KEY]/settings/issuetypes/xxxxx

Obtain an API token

Now it's time to obtain an API token in order to build a bridge between our Teneo bot and Jira.

Log in to Jira portal as the user you created above.
Click the avatar icon on the upper right corner of portal page.
Click on 'Account settings' and new tab window will be opened.
On left side panel menu, select the 'Security' menu.
Select 'Create and manage API tokens' under 'API token' section.
Select the 'Create API token' button and enter Label value and click on the 'Create' button.
Atlassian portal would generate new API token for you and this should be copied and secured immediately as this requires for you to login to JiraConnectorApi Teneo bot to perform various operations.

Be sure to store this somewhere safe before selecting 'Save' as the API token will only be displayed once in the UI. Using hardcoded API tokens in your solution is recommended for testing purposes only.

Add credentials to your solution

The solution contains global variables JiraConnectorApi_sLoginUserEmailId, JiraConnectorApi_sAPIToken and JiraConnectorApi_sJiraServiceEndPointBaseURL in which various credentials we have collected should be stored. The value of the global variable should be a type of String like this:

Variable Name	Example value	Description
JiraConnectorApi_sLoginUserEmailId	'teneo@example.com'	Jira user account email id.
JiraConnectorApi_sAPIToken	'ksdf345***'	API token generated via Atlassian software.
JiraConnectorApi_sJiraServiceEndPointBaseURL	'https://xxxxxxxx.atlassian.net/'	Base URL of JIRA service end point.

To update the global variables, proceed as follows:

In a text editor, update each of above global variables by pasting in the values you have collected in the steps above.
In you JiraConnectorApi solution, click the 'Solution' tab and select 'Globals' in the purple navigation bar.
Select the 'Variables' tab at the top, select the variables called, JiraConnectorApi_sLoginUserEmailId, JiraConnectorApi_sAPIToken and JiraConnectorApi_sJiraServiceEndPointBaseURL.
In the panel on the right, click 'Edit'. You can now update the value of the variable by pasting the updated string values.
When done, click 'Save All' in the top right corner.

Test in Try Out

Your solution is now ready. You can test this in Try Out by asking I want to login. The Teneo bot would then start asking you to input for follow up questions and then answer should provide the tickets, which are assigned to a user from Jira portal.

Example conversations

User: I want to login.
Bot: Please enter your JIRA account email id.
User: teneo@example.com
Bot: Please enter your JIRA API token. Note: Check with your Jira administrator, if you don't have one.
User: ksdf345*****
Bot: Please enter an instance url provided by Jira.
User: https://xxxxxx.atlassian.net
Bot: Hi teneo@example.com, Your login has been successful!

User: I want to create a new JIRA ticket
Bot: Please choose one of the following issue types, Epic Story Task Bug Subtask
User: Story
Bot: Please enter the summary of issue
User: My first Jira story summary via Teneo Bot
Bot: Please enter the description of issue
User: Story descr via Teneo Bot
Bot: New JIRA ticket TEN-1 has been created successfully.

User: I would like to assign a ticket to user
Bot: Please enter an existing JIRA ticket id.
User: TEN-1
Bot: Please enter an assignee name. Note : Assignee name is case sensitive.
User: John Doe
Bot: JIRA ticket id TEN-1 has been assigned to John Doe successfully!

User: I wish to see tickets assigned to other user
Bot: Please enter an assignee name. Note : Assignee name is case sensitive.
User: John Doe
Bot: Below are list of tickets assigned to John Doe,
TEN-1

User: Can I retrieve tickets reported by someone
Bot: Please enter an reporter name. Note : Reporter name is case sensitive.
User: John Doe
Bot: Below are list of tickets reported by John Doe,
TEN-2, TEN-4, TEN-10

User: I need to modify a jira ticket
Bot: Please enter an existing JIRA ticket id.
User: TEN-1
Bot: Please choose one of the following issue fields,
Summary
Description
Priority
User: Priority
Bot: Please choose one of the following priority levels
Higher
High
Medium
Low
Lower
User: Higher
Bot: Priority field has been updated on JIRA ticket id TEN-1 successfully!

User: I need to delete a jira ticket
Bot: Please enter an existing JIRA ticket id.
User: TEN-1
Bot: JIRA ticket TEN-1 has been deleted successfully!

User : I want to filter tickets
Bot : Please choose a filter of your choice. Note : Filter name is case sensitive
Filter1
Filter2
Filter6
User: Filter1
Bot: Below are list of tickets from your filter search,
TEN-2, TEN-3, TEN-5

User: I want to logout
Bot: Your logout has been successful!

For simplicity, the bot answers in this solution are text only. Depending on the channel, interactive cards can be added, for example to add buttons or allow the user to select items from a list.

More on authentication

Jira offers multiple authentication methods including OAuth Authentication, API token-based authentication and Basic authentication by using username and password that developers can use to allow their users to authenticate with Jira. Which authentication flow to use depends on the type of application and the use case.

This Jira solution contains a flow called 'Bot asks a user to login into JIRA'. This flow is responsible to set a value of global variable called JiraConnectorApi_bHasUserLoggedIn which is included at the beginning of each other flows that checks the user's authentication to access the flows. This flow checks if the global variable JiraConnectorApi_sAPIToken contains an API token which is needed to perform API requests. If the JiraConnectorApi_bHasUserLoggedIn variable is false, this flow answers a user authentication failure message.

By default, the Jira 'Bot asks a user to login into JIRA' flow uses the stored credentials from global variables to authenticate the user. This flow uses Jira's API token-based authentication mechanism, which provides instructions in the getting started section on this page explain how to prepare your solution using this authentication approach.

This authentication uses stored credentials from global variables JiraConnectorApi_sLoginUserEmailId, JiraConnectorApi_sAPIToken and JiraConnectorApi_sJiraServiceEndPointBaseURL to prepare an authentication with Jira and it generates a Base64 encoded authorization header value on another global variable JiraConnectorApi_sJIRABasicAuthToken and checks an access against Jira project site url stored on JiraConnectorApi_sJiraServiceEndPointBaseURL and return a successful authentication. The value generated for global variable JiraConnectorApi_sJIRABasicAuthToken looks like this:

Variable Name	Example value	Description
JiraConnectorApi_sJIRABasicAuthToken	'Basic Ymtrngfh76k****2='	Basic auth token (Base64 encoded) to access JIRA resources via REST API.

This Base64 encoded value is then stored in the global variable JiraConnectorApi_sJIRABasicAuthToken, so it can be used for subsequent requests that require authentication across flows in the Jira solution. The global variable is used by the Jira integration for the various REST requests.

The solution uses the stored credentials approach by default, mostly because it is easiest and quickest to get started. However, because this authentication flow passes the user’s credentials back and forth it is advised to use this authentication method for development purposes only. Additionally, using stored credentials means that all objects created by the bot are created by the same user. Therefore, it might be preferred to implement an authentication flow that enables Teneo to interact with Jira on the user's behalf.

However, this authentication flow can still be used in production grade only when a frontend connector or a channel connector supplies necessary user credentials instead of hardcoding them in Teneo in a more secured way by using any industrial standard encryption techniques.

The authentication flow for the API token based authentication in combination with Teneo roughly looks like this:

Jira - diagram

For more details on Jira and API token authentication, see: Digging Deeper into API token in Jira

Download

Download the solution here.
Import the solution into Teneo. For more details see: How to import solutions.