This document explains how to configure the Jira v2.3.0 plugin with the Ticket Orchestrator module of the Netskope Cloud Exchange platform. This plugin is used to create tickets for selected Jira projects on the Jira Cloud Platform. It also supports updating tickets and syncing their status.
Prerequisites
- A Netskope tenant (or multiple, for example, production and development/test instances).
- A Netskope Cloud Exchange tenant with the the Tenant plugin and Ticket Orchestrator plugin already configured.
- Jira instance with an account.
- Connectivity to the following host: https://*.atlassian.net/.
Jira Plugin Support
This plugin is used to create tickets for selected Jira projects on the Jira Cloud Platform. It also supports updating tickets and syncing their status.
| Description | Supported Types |
|---|---|
| Alerts for Tickets | Compromised Credentials, Policy, Malsite, Malware, DLP, Security Assessment, Watchlist, Quarantine, Remediation, UBA, CTEP, Device, Content |
| Events for Tickets | Endpoint, Incident |
Mappings
Queue Mapping
| Description | Types |
|---|---|
| Default mapped fields for custom message of Summary. | Netskope $appCategory Alert name: $alertName; Event Name: $alert_name |
| Default mapped fields for custom message of Description | Alert/Event ID: $idAlert/Event ID: $idAlert/Event App: $appAlert/Event User: $userAlert Name: $alertNameAlert Type: $alertTypeAlert App Category: $appCategoryEvent Name: $alert_nameEvent Type: $eventType |
Default Status Mapping
| Cloud Exchange Status | Value | Jira Status |
|---|---|---|
| New | New | New |
| In Progress | In Progress | In Progress |
| On Hold | – | Default will be blank User can create custom status on Jira project to map |
| Closed | Closed | Closed |
| Deleted | – | Default will be blank User can create custom status on Jira project to map |
| Other | – | Default will be blank User can create custom status on Jira project to map |
Note
Default status in the Jira plugin may vary, as these fields can be customized within the platform. Any status which is not mapped with corresponding Cloud Exchange fields, then it will not sync the status of the ticket.
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
| API Endpoint | Method | Use Case |
|---|---|---|
| /rest/api/3/myself | GET | Validate a Jira user. |
| /rest/api/3/field | GET | Get available ticket fields. |
| /rest/api/3/project/search | GET | Get all projects from the Jira platform. |
| /rest/api/3/issue/<issue_id> | GET | Get particular ticket details. |
| /rest/api/3/issue/createmeta/<project_id>/issuetypes/<issue_type_id> | GET | Get ticket fields for a given project and ticket type. |
| /rest/api/3/issue | POST | Create a ticket on the Jira platform. |
| /rest/api/3/search/jql | POST | Search Jira tickets for a given query. |
| /rest/api/3/issue/{issue_id}/editmeta | GET | Get ticket fields for a given ticket ID to edit. |
| /rest/api/3/issue/<issue_id> | PUT | Update a Jira ticket. |
| /rest/api/3/issue/<issue_id>/transitions | GET | Get Jira tickets transitions (statuses). |
| /rest/api/3/issue/<issue_id>/transitions | POST | Set Jira tickets status. |
| /rest/api/3/users/search | GET | Get Jira Users. |
Validate a Jira User
API Endpoint: <Instance URL>/rest/api/3/myself
Method: GET
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Sample API Response (Status Code: 200)
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/user?accountId=712020:d2bb6886-8c0c-4aff-9d5c-4723e20kk7cb",
"accountId": "712020:d2bb6960-8c0c-4aff-9d5c-4723e20ff6cb",
"accountType": "atlassian",
"emailAddress": "user@gmail.com",
"avatarUrls": {
"48x48": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png",
"24x24": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png",
"16x16": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png",
"32x32": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png"
},
"displayName": "User",
"active": true,
"timeZone": "Asia/Calcutta",
"locale": "en_US",
"groups": {
"size": 4,
"items": []
},
"applicationRoles": {
"size": 3,
"items": []
},
"expand": "groups,applicationRoles"
}
Get Available Ticket Fields
API Endpoint: <Instance URL>/rest/api/3/field
Method: GET
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Sample API Response (Status Code: 200)
[
{
"id": "statuscategorychangedate",
"key": "statuscategorychangedate",
"name": "Status Category Changed",
"custom": false,
"orderable": false,
"navigable": true,
"searchable": true,
"clauseNames": [
"statusCategoryChangedDate"
],
"schema": {
"type": "datetime",
"system": "statuscategorychangedate"
}
},
……
]
Get All Projects from the Jira Platform
API Endpoint: <Instance URL>/rest/api/3/project/search
Method: GET
Parameters
| Key | Value |
|---|---|
| startAt | 0 |
| maxResults | 50 |
| expand | issueTypes |
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Sample API Response (Status Code: 200)
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/project/search?expand=issueTypes&maxResults=50&startAt=0",
"maxResults": 50,
"startAt": 0,
"total": 1,
"isLast": true,
"values": [
{
"expand": "description,lead,issueTypes,url,projectKeys,permissions,insight",
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/project/10015",
"id": "10015",
"key": "JD",
"issueTypes": [
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10045",
"id": "10045",
"description": "Tasks track small, distinct pieces of work.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium",
"name": "Task",
"subtask": false,
"avatarId": 10318,
"hierarchyLevel": 0
},
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10046",
"id": "10046",
"description": "Bugs track problems or errors.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10303?size=medium",
"name": "Bug",
"subtask": false,
"avatarId": 10303,
"hierarchyLevel": 0
},
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10047",
"id": "10047",
"description": "Stories track functionality or features expressed as user goals.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10315?size=medium",
"name": "Story",
"subtask": false,
"avatarId": 10315,
"hierarchyLevel": 0
},
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10048",
"id": "10048",
"description": "Epics track collections of related bugs, stories, and tasks.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10307?size=medium",
"name": "Epic",
"subtask": false,
"avatarId": 10307,
"hierarchyLevel": 1
},
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10049",
"id": "10049",
"description": "Subtasks track small pieces of work that are part of a larger task.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10316?size=medium",
"name": "Subtask",
"subtask": true,
"avatarId": 10316,
"hierarchyLevel": -1
}
],
"name": "Jira Demo",
"avatarUrls": {
"48x48": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418",
"24x24": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418?size=small",
"16x16": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418?size=xsmall",
"32x32": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418?size=medium"
},
"projectTypeKey": "software",
"simplified": true,
"style": "next-gen",
"isPrivate": false,
"properties": {},
"entityId": "84af9cba-b5cb-4c95-8df6-3ac5ef8b9f24",
"uuid": "84af9cba-b5cb-4c95-8df6-3ac5ef8b9f24"
}
]
}
Get Ticket Details
API Endpoint: <Instance URL>/rest/api/3/issue/<issue_id>
Method: GET
Path Parameters
| Key | Value |
|---|---|
| issue_id | JD-1 |
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Sample API Response (Status Code: 200)
{
"expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations,customfield_10010.requestTypePractice",
"id": "308014",
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issue/308014",
"key": "JD-1",
"fields": {
"statuscategorychangedate": "2024-11-29T20:31:30.112+0530",
"issuetype": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10045",
"id": "10045",
"description": "Tasks track small, distinct pieces of work.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium",
"name": "Task",
"subtask": false,
"avatarId": 10318,
"entityId": "2c509b1e-1b97-4cb0-9401-1e9433b6c79e",
"hierarchyLevel": 0
},
"timespent": null,
"customfield_10030": null,
"project": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/project/10015",
"id": "10015",
"key": "JD",
"name": "Jira Demo",
"projectTypeKey": "software",
"simplified": true,
"avatarUrls": {
"48x48": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418",
"24x24": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418?size=small",
"16x16": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418?size=xsmall",
"32x32": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418?size=medium"
}
},
"customfield_10032": null,
"fixVersions": [],
"customfield_10033": null,
"aggregatetimespent": null,
"resolution": null,
"customfield_10037": null,
"customfield_10027": null,
"customfield_10028": null,
"customfield_10029": null,
"resolutiondate": null,
"workratio": -1,
"issuerestriction": {
"issuerestrictions": {},
"shouldDisplay": true
},
"watches": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issue/JD-1/watchers",
"watchCount": 1,
"isWatching": true
},
"lastViewed": null,
"created": "2024-11-29T20:31:29.691+0530",
"customfield_10020": null,
"customfield_10021": null,
"customfield_10022": null,
"priority": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/priority/3",
"iconUrl": "https://cto-jira-plugin.atlassian.net/images/icons/priorities/medium.svg",
"name": "Medium",
"id": "3"
},
"customfield_10023": null,
"customfield_10024": null,
"customfield_10025": null,
"labels": [],
"customfield_10026": null,
"customfield_10016": null,
"customfield_10017": null,
"customfield_10018": {
"hasEpicLinkFieldDependency": false,
"showField": false,
"nonEditableReason": {
"reason": "PLUGIN_LICENSE_ERROR",
"message": "The Parent Link is only available to Jira Premium users."
}
},
"customfield_10019": "0|i1aoqv:",
"timeestimate": null,
"aggregatetimeoriginalestimate": null,
"versions": [],
"issuelinks": [],
"assignee": null,
"updated": "2024-11-29T20:31:29.820+0530",
"status": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/status/10063",
"description": "",
"iconUrl": "https://cto-jira-plugin.atlassian.net/",
"name": "To Do",
"id": "10063",
"statusCategory": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/statuscategory/2",
"id": 2,
"key": "new",
"colorName": "blue-gray",
"name": "To Do"
}
},
"components": [],
"timeoriginalestimate": null,
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Alert/Event ID: 6ffc31d320e423d77c1761f4\nAlert/Event App: \nAlert/Event User: kamlesh.solanki@crestdatasys.com\n\nAlert Name: Fallback Action\nAlert Type: policy\nAlert App Category: Business\n\nEvent Name: value_unavailable\nEvent Type: value_unavailable"
}
]
}
]
},
"customfield_10010": null,
"customfield_10014": null,
"customfield_10015": null,
"timetracking": {},
"customfield_10005": null,
"customfield_10006": null,
"customfield_10007": null,
"security": null,
"customfield_10008": null,
"customfield_10009": null,
"aggregatetimeestimate": null,
"attachment": [],
"summary": "Netskope Business alert name: Fallback Action, Event Name: value_unavailable",
"creator": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/user?accountId=712020%3Ad2bb6960-8c0c-4aff-9d5c-4723e20ff6cb",
"accountId": "712020:d2bb6960-8c0c-4aff-9d5c-4723e20ff6cb",
"emailAddress": "kaushalpatel0506@gmail.com",
"avatarUrls": {
"48x48": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png",
"24x24": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png",
"16x16": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png",
"32x32": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png"
},
"displayName": "Kaushal Patel",
"active": true,
"timeZone": "Asia/Calcutta",
"accountType": "atlassian"
},
"subtasks": [],
"customfield_10040": null,
"customfield_10041": null,
"customfield_10042": null,
"customfield_10043": null,
"reporter": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/user?accountId=712020%3Ad2bb6960-8c0c-4aff-9d5c-4723e20ff6cb",
"accountId": "712020:d2bb6960-8c0c-4aff-9d5c-4723e20ff6cb",
"emailAddress": "kaushalpatel0506@gmail.com",
"avatarUrls": {
"48x48": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png",
"24x24": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png",
"16x16": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png",
"32x32": "https://secure.gravatar.com/avatar/c20e29843b8be2868b51047c06d2f0b9?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-5.png"
},
"displayName": "Kaushal Patel",
"active": true,
"timeZone": "Asia/Calcutta",
"accountType": "atlassian"
},
"customfield_10044": null,
"aggregateprogress": {
"progress": 0,
"total": 0
},
"customfield_10045": null,
"customfield_10001": null,
"customfield_10002": [],
"customfield_10046": null,
"customfield_10003": null,
"customfield_10047": null,
"customfield_10004": null,
"customfield_10048": [],
"customfield_10038": null,
"customfield_10039": [],
"environment": null,
"duedate": null,
"progress": {
"progress": 0,
"total": 0
},
"votes": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issue/JD-1/votes",
"votes": 0,
"hasVoted": false
},
"comment": {
"comments": [],
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issue/308014/comment",
"maxResults": 0,
"total": 0,
"startAt": 0
},
"worklog": {
"startAt": 0,
"maxResults": 20,
"total": 0,
"worklogs": []
}
}
}
Get Ticket Fields for a Given Project and Ticket Type
API Endpoint: <Instance URL>/rest/api/3/issue/createmeta/<project_id>/issuetypes/<issue_type_id>
Method: GET
Path Parameters
| Key | Value |
|---|---|
| project_id | 10015 |
| issue_type_id | 10045 |
Parameters
| Key | Value |
|---|---|
| startAt | 0 |
| maxResults | 200 |
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Sample API Response (Status Code: 200)
{
"startAt": 0,
"maxResults": 200,
"total": 16,
"fields": [
{
"required": false,
"schema": {
"type": "user",
"system": "assignee"
},
"name": "Assignee",
"key": "assignee",
"autoCompleteUrl": "https://cto-jira-plugin.atlassian.net/rest/api/3/user/assignable/search?project=JD&query=",
"hasDefaultValue": false,
"operations": [
"set"
],
"fieldId": "assignee"
},
{
"required": false,
"schema": {
"type": "array",
"items": "attachment",
"system": "attachment"
},
"name": "Attachment",
"key": "attachment",
"hasDefaultValue": false,
"operations": [
"set",
"copy"
],
"fieldId": "attachment"
},
{
"required": false,
"schema": {
"type": "any",
"custom": "com.atlassian.jira.plugins.jira-development-integration-plugin:devsummarycf",
"customId": 10000
},
"name": "Development",
"key": "customfield_10000",
"hasDefaultValue": false,
"operations": [
"set"
],
"fieldId": "customfield_10000"
},
{
"required": false,
"schema": {
"type": "team",
"custom": "com.atlassian.jira.plugin.system.customfieldtypes:atlassian-team",
"customId": 10001,
"configuration": {
"com.atlassian.jira.plugin.system.customfieldtypes:atlassian-team": true
}
},
"name": "Team",
"key": "customfield_10001",
"autoCompleteUrl": "https://cto-jira-plugin.atlassian.net/gateway/api/v1/recommendations",
"hasDefaultValue": false,
"operations": [
"set"
],
"fieldId": "customfield_10001"
},
{
"required": false,
"schema": {
"type": "number",
"custom": "com.pyxis.greenhopper.jira:jsw-story-points",
"customId": 10016
},
"name": "Story point estimate",
"key": "customfield_10016",
"hasDefaultValue": false,
"operations": [
"set"
],
"fieldId": "customfield_10016"
},
{
"required": false,
"schema": {
"type": "any",
"custom": "com.pyxis.greenhopper.jira:gh-lexo-rank",
"customId": 10019
},
"name": "Rank",
"key": "customfield_10019",
"hasDefaultValue": false,
"operations": [
"set"
],
"fieldId": "customfield_10019"
},
{
"required": false,
"schema": {
"type": "array",
"items": "json",
"custom": "com.pyxis.greenhopper.jira:gh-sprint",
"customId": 10020
},
"name": "Sprint",
"key": "customfield_10020",
"hasDefaultValue": false,
"operations": [
"set"
],
"fieldId": "customfield_10020"
},
{
"required": false,
"schema": {
"type": "array",
"items": "option",
"custom": "com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes",
"customId": 10021
},
"name": "Flagged",
"key": "customfield_10021",
"hasDefaultValue": false,
"operations": [
"add",
"set",
"remove"
],
"allowedValues": [
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/customFieldOption/10019",
"value": "Impediment",
"id": "10019"
}
],
"fieldId": "customfield_10021"
},
{
"required": false,
"schema": {
"type": "string",
"system": "description"
},
"name": "Description",
"key": "description",
"hasDefaultValue": false,
"operations": [
"set"
],
"fieldId": "description"
},
{
"required": false,
"schema": {
"type": "array",
"items": "issuelinks",
"system": "issuelinks"
},
"name": "Linked Issues",
"key": "issuelinks",
"autoCompleteUrl": "https://cto-jira-plugin.atlassian.net/rest/api/3/issue/picker?currentProjectId=&showSubTaskParent=true&showSubTasks=true¤tIssueKey=null&query=",
"hasDefaultValue": false,
"operations": [
"add",
"copy"
],
"fieldId": "issuelinks"
},
{
"required": true,
"schema": {
"type": "issuetype",
"system": "issuetype"
},
"name": "Issue Type",
"key": "issuetype",
"hasDefaultValue": false,
"operations": [],
"allowedValues": [
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10045",
"id": "10045",
"description": "Tasks track small, distinct pieces of work.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium",
"name": "Task",
"subtask": false,
"avatarId": 10318,
"entityId": "2c509b1e-1b97-4cb0-9401-1e9433b6c79e",
"hierarchyLevel": 0
}
],
"fieldId": "issuetype"
},
{
"required": false,
"schema": {
"type": "array",
"items": "string",
"system": "labels"
},
"name": "Labels",
"key": "labels",
"autoCompleteUrl": "https://cto-jira-plugin.atlassian.net/rest/api/1.0/labels/suggest?query=",
"hasDefaultValue": false,
"operations": [
"add",
"set",
"remove"
],
"fieldId": "labels"
},
{
"required": false,
"schema": {
"type": "issuelink",
"system": "parent"
},
"name": "Parent",
"key": "parent",
"hasDefaultValue": false,
"operations": [
"set"
],
"fieldId": "parent"
},
{
"required": true,
"schema": {
"type": "project",
"system": "project"
},
"name": "Project",
"key": "project",
"hasDefaultValue": false,
"operations": [
"set"
],
"allowedValues": [
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/project/10015",
"id": "10015",
"key": "JD",
"name": "Jira Demo",
"projectTypeKey": "software",
"simplified": true,
"avatarUrls": {
"48x48": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418",
"24x24": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418?size=small",
"16x16": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418?size=xsmall",
"32x32": "https://cto-jira-plugin.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10418?size=medium"
}
}
],
"fieldId": "project"
},
{
"required": true,
"schema": {
"type": "user",
"system": "reporter"
},
"name": "Reporter",
"key": "reporter",
"autoCompleteUrl": "https://cto-jira-plugin.atlassian.net/rest/api/3/user/recommend?context=Reporter&issueKey=",
"hasDefaultValue": true,
"operations": [
"set"
],
"fieldId": "reporter"
},
{
"required": true,
"schema": {
"type": "string",
"system": "summary"
},
"name": "Summary",
"key": "summary",
"hasDefaultValue": false,
"operations": [
"set"
],
"fieldId": "summary"
}
]
}
Create a Ticket on the Jira Platform
API Endpoint: <Instance URL>/rest/api/3/issue
Method: POST
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Body
{
"fields": {
"issuetype": {
"id": "10045"
},
"project": {
"id": "10015"
},
"summary": "Netskope Business alert name: Fallback Action, Event Name: value_unavailable",
"description": {
"content": [
{
"content": [
{
"text": "Alert/Event ID: 6ffc31d320e423d77c1761f4\nAlert/Event App: \nAlert/Event User: kamlesh.solanki@crestdatasys.com\n\nAlert Name: Fallback Action\nAlert Type: policy\nAlert App Category: Business\n\nEvent Name: value_unavailable\nEvent Type: value_unavailable",
"type": "text"
}
],
"type": "paragraph"
}
],
"type": "doc",
"version": 1
}
}
}
Sample API Response (Status Code: 201)
{
"id": "308126",
"key": "JD-113",
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issue/308126"
}
Search Jira Tickets for a Given Query
API Endpoint: <Instance URL>/rest/api/3/search/jql
Method: POST
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Body
{
"jql": "key IN JD-1",
"maxResults": 100,
"fields": [
"status",
"assignee"
],
"nextPageToken": next_page_token,
}
Sample API Response (Status Code: 200)
{
"issues": [
{
"expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
"fields": {
"assignee": null,
"status": {
"description": "",
"iconUrl": "https://cto-jira-plugin.atlassian.net/",
"id": "10063",
"name": "To Do",
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/status/10063",
"statusCategory": {
"colorName": "blue-gray",
"id": 2,
"key": "new",
"name": "To Do",
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/statuscategory/2"
}
}
},
"id": "308015",
"key": "JD-2",
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issue/308015"
}
],
"nextPageToken": "ChUjU3RyaW5nJlNrUT0lSW50Jk1nPT0QARjs0su-3TI="
}
Get Ticket Fields for a Given Ticket ID to Edit
API Endpoint: <Instance URL>/rest/api/3/issue/<issue_id>/editmeta
Method: GET
Path Parameters
| Key | Value |
|---|---|
| issue_id | JD-1 |
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Sample API Response (Status Code: 200)
{
"fields": {
"summary": {
"required": true,
"schema": {
"type": "string",
"system": "summary"
},
"name": "Summary",
"key": "summary",
"operations": [
"set"
]
},
"issuetype": {
"required": true,
"schema": {
"type": "issuetype",
"system": "issuetype"
},
"name": "Issue Type",
"key": "issuetype",
"operations": [],
"allowedValues": [
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10045",
"id": "10045",
"description": "Tasks track small, distinct pieces of work.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium",
"name": "Task",
"subtask": false,
"avatarId": 10318,
"entityId": "2c509b1e-1b97-4cb0-9401-1e9433b6c79e",
"hierarchyLevel": 0
},
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10046",
"id": "10046",
"description": "Bugs track problems or errors.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10303?size=medium",
"name": "Bug",
"subtask": false,
"avatarId": 10303,
"entityId": "7d5c7d87-29c6-4d3d-b388-a2b773697166",
"hierarchyLevel": 0
},
{
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/issuetype/10047",
"id": "10047",
"description": "Stories track functionality or features expressed as user goals.",
"iconUrl": "https://cto-jira-plugin.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10315?size=medium",
"name": "Story",
"subtask": false,
"avatarId": 10315,
"entityId": "d678842a-3080-40da-a68d-cacbbb097980",
"hierarchyLevel": 0
}
]
},
……
}
}
Update a Jira Ticket
API Endpoint: <Instance URL>/rest/api/3/issue/<issue_id>
Method: PUT
Path Parameters
| Key | Value |
|---|---|
| issue_id | JD-1 |
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Body
{
"update": {
"comment": [
{
"add": {
"body": {
"content": [
{
"content": [
{
"text": "Received new alert/event with Alert/Event ID: $id and Alert Name: $alertName, Event Name: $alert_name in Cloud Exchange.",
"type": "text"
}
],
"type": "paragraph"
}
],
"type": "doc",
"version": 1
}
}
}
]
}
}
Sample API Response (Status Code: 204)
No Content
Get Jira Tickets Transitions (Statuses)
API Endpoint: <Instance URL>/rest/api/3/issue/<issue_id>/transitions
Method: GET
Path Parameters
| Key | Value |
|---|---|
| issue_id | JD-1 |
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Sample API Response (Status Code: 200)
{
"expand": "transitions",
"transitions": [
{
"id": "11",
"name": "To Do",
"to": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/status/10063",
"description": "",
"iconUrl": "https://cto-jira-plugin.atlassian.net/",
"name": "To Do",
"id": "10063",
"statusCategory": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/statuscategory/2",
"id": 2,
"key": "new",
"colorName": "blue-gray",
"name": "To Do"
}
},
"hasScreen": false,
"isGlobal": true,
"isInitial": false,
"isAvailable": true,
"isConditional": false,
"isLooped": false
},
{
"id": "21",
"name": "In Progress",
"to": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/status/10064",
"description": "",
"iconUrl": "https://cto-jira-plugin.atlassian.net/",
"name": "In Progress",
"id": "10064",
"statusCategory": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/statuscategory/4",
"id": 4,
"key": "indeterminate",
"colorName": "yellow",
"name": "In Progress"
}
},
"hasScreen": false,
"isGlobal": true,
"isInitial": false,
"isAvailable": true,
"isConditional": false,
"isLooped": false
},
{
"id": "31",
"name": "Done",
"to": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/status/10065",
"description": "",
"iconUrl": "https://cto-jira-plugin.atlassian.net/",
"name": "Done",
"id": "10065",
"statusCategory": {
"self": "https://cto-jira-plugin.atlassian.net/rest/api/3/statuscategory/3",
"id": 3,
"key": "done",
"colorName": "green",
"name": "Done"
}
},
"hasScreen": false,
"isGlobal": true,
"isInitial": false,
"isAvailable": true,
"isConditional": false,
"isLooped": false
}
]
}
Set Jira Tickets Status
API Endpoint: <Instance URL>/rest/api/3/issue/<issue_id>/transitions
Method: GET
Path Parameters
| Key | Value |
|---|---|
| issue_id | JD-1 |
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Body
{
"transition": {
"id": "31"
}
}
Get Jira Users
API Endpoint: <Instance URL>/rest/api/3/users/search
Method: GET
Parameters
| Key | Value |
|---|---|
| startAt | 0 |
| maxResults | 1000 |
Headers
| Key | Value |
|---|---|
| User-Agent | netskope-ce-6.0.0-cto-jira-v2.3.0 |
| Authorization | Basic <user_email:api_key> |
Sample API Response (Status Code: 200)
[
{
"self": "https://jira-itsm-crest.atlassian.net/rest/api/3/user?accountId=61c031260586a2006981a3a5",
"accountId": "61c031260586a2006981a3a5",
"accountType": "atlassian",
"emailAddress": "kaushal.patel@crestdata.ai",
"avatarUrls": {
"48x48": "https://secure.gravatar.com/avatar/70b3242c928f8da4c3d4f05cb06e294b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-6.png",
"24x24": "https://secure.gravatar.com/avatar/70b3242c928f8da4c3d4f05cb06e294b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-6.png",
"16x16": "https://secure.gravatar.com/avatar/70b3242c928f8da4c3d4f05cb06e294b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-6.png",
"32x32": "https://secure.gravatar.com/avatar/70b3242c928f8da4c3d4f05cb06e294b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FKP-6.png"
},
"displayName": "Kaushal Patel",
"active": true,
"locale": "en_US"
},
….
]
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.
| Description | Specifications |
|---|---|
| Stack details | Size: Large RAM: 32 GB CPU: 16 Cores |
Tickets created per minute | ~ 45 tickets |
User Agent
The user agent added for this plugin is in the following format:
netskope-ce-6.0.0-cto-jira-v2.3.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.
Watch a Video
Click play to watch a video.
Get your Jira API Token
- To create a new Jira Cloud API key, log in Jira and go to Your Profile and Settings and click on Profile.
- Click Manage your account.
- Click Security and then click Create and manage API tokens. See Create and manage API tokens.
- Click Create API token.
- Enter a Name for your token and click Create.
- Click Copy, and save the token to use in the plugin configuration. Click Done.
Note
This token will only be available/visible at the time of creation. This token will be used to configure the Ticket Orchestrator JIRA plugin in Cloud Exchange.
Configure the Jira Plugin
- In Cloud Exchange, go to Settings > Plugin Store. Search for and select the Jira v2.3.0 (CTO) plugin box.
- Enter a Configuration Name and change the Sync Interval as per your requirement.
- Click Next and enter the Authentication parameters:
- Jira Cloud Instance URL: Jira Cloud instance URL.
- Email Address: Email address of the Jira user.
- API Token: API token of the Jira user.
- Click Next and enter the Jira Issue Types in comma-separated values (like
Task,Bug). The issue type values are case-sensitive. issue type values having “,” are not supported.(e.g. “Bu,gs”) and issue type value associated with at least one project will be supported.
- Provide the mapping configuration from the following fields. When finished, click Save.
- Here is the default mapping for status mapping:
- To create a custom status, select the predefined options you want and click Add at the bottom.
- To create a new Cloud Exchange field, click Add New.
- Enter a field name and click Add Field and map it to the the status of your choice. When finished, click Save to configure the plugin.
Create a Ticket Orchestrator Business Rule for Jira
Create a business rule based on the filters you need to create tickets in the Jira platform.
- In Ticket Orchestrator, go to Business Rules.
- Click Create New Rule.
- Enter a Rule Name and build the appropriate filter query condition on the field(s) for the business rule. You can also type the query manually by clicking Filter Query.
- Click Save.
Add a Ticket Orchestrator Queue for Jira
- In Ticket Orchestrator, go to Queues.
- Click Add Queue Configuration and select the Business Rule, a plugin Configuration, and a queue from the dropdowns. Add and map appropriate values between alerts and incidents in the Map Fields section. Alert attributes can be accessed using $ in the custom message field. Click Add to add more field mappings.
- Click Save and sync the queue if you already have the alerts/events pulled.
Note
- Assignee field can be mapped with the Cloud Exchange field containing the user email or email as a string or user id as a string. Note that the mapped email id must have a user on the same JIRA instance and email visibility is set to “Anyone” for assignees under the user’s privacy settings under Account Settings.
- The user must provide the value of the field in its respective schema except the Assignee field. For most of the fields, the schema is available herehere.
- For status field mapping, provide value in Netskope event status format.
- To update the incident status on Netskope, refer to the Netskope plugin guide for CTO.
- Assignee field can be mapped with the Cloud Exchange field containing the user email or email as a string or user id as a string. Note that the mapped email id must have a user on the same JIRA instance and email visibility is set to “Anyone” for assignees under the user’s privacy settings under Account Settings.
Validate the Jira Plugin
Validate in Cloud Exchange
In order to validate the workflow, you must have Netskope Alerts/Events.
- To view the list of tickets created in Jira, go to Tickets in Ticket Orchestrator.
Note
- In Review is a custom status created in the Cloud Exchange.
- If you were already using the Jira plugin on an older Netskope Cloud Exchange tenant, and you upgrade Cloud Exchange to v6.0.0, then you may see different colors for the same status under the Ticket Status field on the Tickets page.
- In Review is a custom status created in the Cloud Exchange.
- Verify Ticket creation on the Logging screen. Go to Settings > Logging and apply the filter with the plugin name.
Note
If your business rule have a deduplication rule added. then it will update the ticket as per your deduplication rule. For Incident events, by default only one ticket will be created for a particular incident. It will only update the ticket if there is no deduplication rule in your business rule.
Validate in Jira
To validate the incident creation, go to Tickets in in Ticket Orchestrator. Click Open on the External Link of the Ticket. Log in to the Jira Cloud and view the newly created ticket.
Troubleshooting the Jira Plugin
Unable to configure the Jira plugin
If user is unable to configure the Jira plugin, it could be due to one of these reasons:
- Incorrect credentials provided.
- The user does not have required permissions.
- Incorrect instance URL provided.
What to do: To solve these issues:
- Make sure to provide correct credentials.
- Make sure that the user has the required permissions.
- Make sure that the correct instance URL is provided.
Unable to create a ticket using the plugin
If you are unable to create a ticket the Jira plugin, it could be due to one of these reasons:
- No alerts or events are available in Cloud Exchange, or no new alerts or events are pulled
- Business Rule has no alerts/events filtered
- The user does not have the required permissions for creating incidents.
- Summary field is not mapped in queue configuration.
What to do: Find the root cause and select the best fit resolution.
- Check if the alerts/events are available in the Alerts/Events page, if no alerts/events are available the ticket won’t be created. Configure your Tenant or other required configuration to create alerts/events in CTO.
- Check the business rule and test it to confirm if it has any alerts filtered, if no alerts are available in the filtering, update the business rule.
- Ensure users have the required permissions.
- Make sure to map Summary with values to create a ticket. Summary is required while creating a ticket.
Unable to create a ticket using the older plugin
If you are using an older plugin version then it expects user id in a JSON schema for Assignee field. After you upgrade the plugin to the latest version, then it expects the user id or user email as a string. So, you may encounter below error while updating already created tickets or creating new tickets:
CTO Jira [CTO Jira]: Received exit code 400, Bad Request while updating ticket with ID 'DEM-10' on Jira platform.
CTO Jira [CTO Jira]: Error occurred while creating a Jira ticket for Alert ID '9e035163ad5cd6bf6fe32999' on Jira platform. Error: The assignee (id) must be a string
What to do: As the older version of this plugin expects the user id in JSON schema for Assignee field and the latest version of this plugin expects either user email or user id in a string, you need to manually change the mapping for Assignee field in the already configured queue.
Queue before plugin upgrade:
After upgrading the plugin to the latest version, you need to manually change the value for the Assignee field in the already configured queue. Example format for the Assignee field is shown bellow:
User ID as a string:
User email as a string:
Directly mapped to any of the CE field containing user email:
Known Behaviors
- For Netskope Cloud Exchange v6.0.0, Jira plugins with versions older than 2.3.0 are not compatible and will not function properly. You are advised to update your Jira plugins to version 2.3.0 or later to ensure full compatibility with Cloud Exchange v6.0.0.
- If you are using an older Jira plugin version on Netskope Cloud Exchange v5.1.2 or older and then you upgrade your Netskope Cloud Exchange to v6.0.0 then the Jira plugin will be updated to CTO Jira v2.3.0 automatically.
- The Ticket Orchestrator Jira plugin does not support sync for severity on Cloud Exchange. So you might observe error logs for skipping severity updates on the Netskope Tenant for incident event when the Update incident back to Netskope Tenant toggle is enabled.
- Due to the current behavior of Cloud Exchange, if you manually sync Ticket Orchestrator queues, you may experience performance issues when the Assignee field is selected. This occurs because additional API calls are made to fetch users from the platform in order to validate the user email.
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
- The plugin also does not support uploading files through Cloud Exchange. That’s why the field Attachment is not be supported.
- 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.
- When a project is deleted, then an already configured queue with that project will be visible as ID.