The JiraConnectorApi example solution showcases how to connect a Teneo solution with the 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.
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.
For each core method in the Jira integration, the solution contains a corresponding example 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.
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.
It's time to create a project on Jira portal in order to perform and experience some CRUD operations by using JiraConnectorApi Teneo bot.
It's important to have a look on your project settings to manage the issue types and fields associated with each issue types.
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.
The URL should look like this: https://[PROJECT_DOMAIN]/jira/software/projects/[PROJECT_KEY]/settings/issuetypes/xxxxx
Now it's time to obtain an API token in order to build a bridge between our Teneo bot and Jira.
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.
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:
Your solution is now ready. You can test this in tryout 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.
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-1User: 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-10User: 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-5User: 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.
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:
For more details on Jira and API token authentication, see: Digging Deeper into API token in Jira
Was this page helpful?