Jira Plugin for Ticket Orchestrator

This document explains how to configure your Jira v1.1.0 plugin integration with the Ticket Orchestrator module of the Netskope Cloud Exchange platform.

Prerequisites

To complete this configuration, you need:

A Netskope tenant (or multiple, for example, production and development/test instances) that is already configured in Cloud Exchange.
A Netskope Cloud Exchange tenant with the Ticket Orchestrator module already configured.
A Jira account.
Connectivity to the following host: https://*.atlassian.net

Compatibility

Netskope CE: v4.1.0, v4.2.0

Performance Matrix

This performance reading has been considered after keeping the plugin running for few hours and taking random readings per minute to collect the average count for the number of tickets that are generated in JIRA. The reading are collected on a Large CE Stack with below mentioned specifications.

Stack Details:

Size: Large

RAM: 32 GB

CPU: 16 Cores

Tickets created on third-party product

~ 50 per minute

Permissions

Project permissions (Refer: https://support.atlassian.com/jira-cloud-administration/docs/manage-project-permissions
- Browse projects
- Create/View issue(s) in any project
- Add comments to the given Jira issue
- Administer Projects
Global Permissions (Refer: https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions)
- Jira Administrator
If issue-level security is configured, issue-level security permission to view the issue(s).

API Details

The plugin uses the Jira Cloud platform REST API to create an issue, get fields, get all projects, get issues, get create issue metadata, get issue state, update issues, and validate credentials from the Jira platform.

Refer to the official documentation for more information on the Jira Cloud platform REST API

https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about

List of APIs Used

API details	Method	Endpoint
Validate authentication	GET	/rest/api/3/myself
Get the list of Jira projects as queues.	GET	/rest/api/3/project/search
Get a list of all the available fields.	GET	/rest/api/3/field/search
Get issues	GET	/rest/api/3/issue/
Get create issue metadata	GET	/rest/api/3/issue/createmeta
Create an issue on the Jira platform	POST	/rest/api/3/issue
Sync issue state	POST	/rest/api/3/search
Update issue on the Jira platform	POST	/rest/api/3/issue/{}/comment

User Agent

The user agent added for this plugin is in the following format: –/ which will be:

netskope-ce-4.2.0-cto-jira itsm-v1.1.0

Workflow

Get a Jira API token.
Configure the Jira plugin.
Configure Ticket Orchestrator Business Rules for Jira.
Configure Ticket Orchestrator Queues for Jira.
Validate the Jira Plugin.

Click play to watch a video.

Get a Jira API Token

To create a new Jira Cloud API key, go to https://id.atlassian.com/manage-profile/security/api-tokens and log in using an account with at least following permissions:
- Project permissions
  - Browse projects
  - Create/View issue(s) in any project
  - Add comments to given Jira issue
  - Administer Projects
  (Refer to: https://support.atlassian.com/jira-cloud-administration/docs/manage-project-permissions/)
- Global permissions: Administer Jira
  (Refer to: https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/)
- If issue-level security is configured, issue-level security permission is also needed to view the issues.
Go to Your Profile and Settings and click Profile.
Click Manage your account.
Click Security (tab), and then click Create and manage API tokens.
Click Create API token.
Enter a descriptive Label for your token and click Create.
Click Copy, and then save the token in a secure place for when you configure the Jira plugin. Note that this token is only available when creating a token.
When finished, click Close.

Configure the Jira Plugin

In Cloud Exchange, go to Settings > Plugins.
Search for and select the Jira v1.1.0 plugin box to open the plugin creation page (make sure the Ticket Orchestrator module is enabled. If not, go to Settings > General and enable the Ticket Orchestrator module).
Enter a Configuration Name.
Adjust the Sync Interval to an appropriate value: Suggested is 5+ minutes.
Click Next.
Enter your Jira Cloud URL. This should be in the following format: https://<your-domain>.atlassian.net.
Enter the user email address for the API token.
Enter your API Token.
Click Next.
Enter the comma-separated Jira issue type(s). Note that the values are case-sensitive.
Click Save.

Configure Ticket Orchestrator Business Rules for Jira

Create a business rule based on the filters you need to generate tickets in the JIRA plugin.

Go to Ticket Orchestrator and click Business Rules.
Click Create new rule.
Enter the appropriate Rule Name in the text box and build the appropriate filter query condition on field(s) for the business rule. You can also type the query manually by clicking Filter Query.
Click Save.
To test the newly created business rule, click on the refresh icon, enter a time period (in days), and click Fetch. This shows the number of alerts that are eligible for incident/ticket creation.

Configure Queues for Jira

Go to Ticket Orchestrator and click Queues.
Click Add Queue Configuration.
Select your previously created Business Rule from the dropdown.
Select the plugin configuration from the dropdown for which the queue is being configured.
Select the Queues from the dropdown. This will list the Jira Projects available on the configured Jira instance. The issues/tickets will be created in the selected project.
Add/Map appropriate values between alerts and incidents under the Map Field section. Alert’s attributes can be accessed via “$” in the custom message field. Click Add to add more field mappings.

Note

The user must provide the value of the field in its respective schema. For most of the fields, the schema is available here.
Click Save.
Based on the business rule(s), Jira tickets for incoming alerts will be created automatically. To create Jira tickets for historical alerts, click the refresh button for the configured queue, enter the time period (in days), and then click Fetch. This shows the number of alerts that are eligible for ticket creation. Click Sync to create Jira tickets for those alerts.

Validate the Jira Plugin

In order to validate the workflow, you must have Netskope Alerts.

Validate In Netskope Cloud Exchange

Go to Ticket Orchestrator and click Alerts.
To view the list tickets created on Jira, go to Tickets.
If tickets are not being created on Jira, you can look at the audit logs in Cloud ExchangeIn Cloud Exchange, click Logging and look through the logs for errors.

Validate In Jira

Click on the External Link of any ticket to directly navigate to the newly created Jira ticket.

Troubleshooting the Jira Plugin

Fields are not appearing in Jira.

Go to your Jira project.
Go to Project Settings > Issue > Screens.
Click Create.
Click Select Field and add the field.

Limitations

There are some common fields that are typically not allowed to be set during the ticket creation via API to ensure data integrity and prevent potential issues.

Common fields that are usually read-only or automatically managed by Jira during a ticket creation. There might be more fields that are set by Jira or not allowed to be set while creating a ticket through APIs.

Below are a few examples of the same:

Status
Created
Updated
Issue ID
Created Date
Updated Date
Created By
Updated By
Key
Images
Request participants
Linked Issues

Netskope also does not support uploading files through CE, which is why the field “Attachment” is not supported.

Jira Plugin for Ticket Orchestrator