HaloITSM Plugin for Ticket Orchestrator

This document explains how to configure the HaloITSM integration with the Ticket Orchestrator module of the Netskope Cloud Exchange platform. This Plugin is used to create tickets on the HaloITSM Platform.

Prerequisites

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 HaloITSM platform account
Connectivity to the following host: https://<tenantname>.haloitsm.com/.

CE Version Compatibility

Netskope CE: v4.2.0, v5.0.0

Plugin Scope

This plugin supports creating tickets for Netskope alerts on the HaloITSM Platform. Only supports ticket creation and ticket status syncing. The HaloITSM plugin does not support updating the tickets (incidents).

Supported Alert types for notifications

Anomaly, Compromised Credentials, policy, Legal Hold, malsite, Malware, DLP, Security Assessment, watchlist, quarantine, Remediation, UBA, CTEP, logs

Permissions

The plugin supports two authentication methods. You can select either one of these. The required permissions for both are:

Authentication Method	Required Checks	Permission
Username & Password	Check Allow Agent LoginsCheck End User Logins	Read:tickets, write:tickets, read:customers
Client ID and Secret (Services)	Login Type: Client	Read:tickets, write:tickets, read:customers

API Details

The plugin utilizes the HaloITSM URL to execute data transmission via a POST request directed at the provided URL.

List of APIs used

API Endpoint	Method	Use Case
https://{tenant}.haloitsm.com/auth/token	POST	Generate Auth Token
https://{tenant}.haloitsm.com/api/Tickets	POST	Create a Ticket
https://{tenant}.haloitsm.com/api/ticket/{ticket_id}	GET	Get Ticket Details
https://{tenant}.haloitsm.com/api/Team	GET	Get Teams

API rate limiting is 300 Requests per rolling 5 minute window.

Generate an Auth Token

Endpoint: https://{tenant}.haloitsm.com/auth/token
Method: POST
Data:

Parameter	Value
grant_type	password
client_id	client_id
username	username
password	password
scope	all

Headers:

Key	Value
Content-Type	application/x-www-form-urlencoded
Accept	application/json

Sample Response:

{
    "scope": "openid email profile offline_access roles read:tickets edit:tickets all",
    "token_type": "Bearer",
    "access_token": "CfDJ8POGWkxqFLROkzHJBRga06w4J4GVbrS1eqMbBFcdMKAPM6d0Jwh4_itC4LczIyl4m9PXonkWZSf-_r-r-WSxxohaWiY_7bi194Q0X9Ni7q-_0pRKlBqd9HAgM91l***********",
    "expires_in": 32400,
    "refresh_token": "2WRrwD8D30fnTiBOng896VePzfXKYuLYhIwrTVnbyznGJXdg1Vu0wCFlfWK1fOJph_AJoBYTScOkHQHPJal_NotAxJN5chrEqv-UqJXr**************",
    "id_token": "3CT3rLSo6E3urFRo9l4NI8TlviYLNQw36_k_aOAASZKoK-3ZmTKrp5fbjg-v827rih4_NSOAKtI2xmWiDzFU***********"
}

Create a Ticket

Endpoint: https://{tenant}.haloitsm.com/api/Tickets
Method: POST
Request Body:

[
    {
        "tickettype_id":1,
        "summary": "This is an example summary",
        "details": "This is an example details message.",
        "category_1": "Business Applications",
        "customfields": [
            {
                "id": "177",
                "value": 1
            },
            {
                "name": "CFImpact",
                "value": "1"
            },
            {
                "name": "CFUrgency",
                "value": "2"
            }
        ]
    }
]

Headers:

Key	Value
Authorization	Bearer <ACCESS_TOKEN>
Content-Type	application/json

Sample Response:

HTTP/1.1 201  Created
Content-Type: application/json

{
    "id": 2290,
    "dateoccurred": "2024-03-20T05:54:37.463",
    "summary": "Netskope CE alert: CE Log",
    "details": "Alert ID: 65fa7a1bc7f689ea87e38cc1\nApp: Cloud Exchange\nAlert Name: CE Log\nAlert Type: Log\nApp Category: CE\nUser: ",
    "status_id": 1,
    "tickettype_id": 1,
    "sla_id": 1,
    "sla_name": "Incident SLA",
    "priority_id": 1,
    "client_id": 12,
    "client_name": "Crest data systems",
    "site_id": 18,
    "site_name": "Main",
    "user_id": 25,
    "user_name": "General User",
    "team": "SHaliniTeam",
    "agent_id": 1,
    "category_1": "Standard Applications>Adobe",
    "category_2": "",
    "category_3": "",
    "category_4": "",
    "onhold": false,
    "respondbydate": "2024-03-20T09:30:00",
    "fixbydate": "2024-03-20T10:00:00",
    "excludefromsla": false,
    "slaholdtime": 0.0,
    "slaactiondate": "2024-03-20T09:30:00",
    "slapercused": 3862.89195755,.....................................
}

Get Ticket Details

Endpoint: https://{tenant}.haloitsm.com/api/ticket/{ticket_id}
Method: GET
Params:
Headers:

Key	Value
Authorization	Bearer <ACCESS_TOKEN>
Content-Type	application/json

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 2290,
    "dateoccurred": "2024-03-20T05:54:37.463",
    "summary": "Netskope CE alert: CE Log",
    "details": "Alert ID: 65fa7a1bc7f689ea87e38cc1\nApp: Cloud Exchange\nAlert Name: CE Log\nAlert Type: Log\nApp Category: CE\nUser: ",
    "status_id": 1,
    "tickettype_id": 1,
    "sla_id": 1,
    "sla_name": "Incident SLA",
    "priority_id": 1,
    "client_id": 12,
    "client_name": "Crest data systems",
    "site_id": 18,
    "site_name": "Main",
    "user_id": 25,
    "user_name": "General User",
    "team": "SHaliniTeam",
    "agent_id": 1,
    "category_1": "Standard Applications>Adobe",
    "category_2": "",
    "category_3": "",
    "category_4": "",
    "onhold": false,
    "respondbydate": "2024-03-20T09:30:00",
    "fixbydate": "2024-03-20T10:00:00",
    "excludefromsla": false,
    "slaholdtime": 0.0,
    "slaactiondate": "2024-03-20T09:30:00",
    "slapercused": 3862.89195755,
    "slatimeleft": -18.81445978775,
    "currentelapsedhours": 19.31445978775,
    "lastactiondate": "2024-03-20T05:54:37.953",
    "organisation_id": 1,
    "department_id": 3,
    "lastincomingemail": "0001-01-01T00:00:00",
    "oppcompanyname": "Crest data systems",
    "oppvalueadjusted": 0.0,
    "cost": 0.0,
    "quantity": 1,
    "source": 3,
    "impactlevel": 0,
    "guid": "766a6955-7ee6-ee11-b9e9-0e3e2f829690",
    "details_html": "Alert ID: 65fa7a1bc7f689ea87e38cc1\nApp: Cloud Exchange\nAlert Name: CE Log\nAlert Type: Log\nApp Category: CE\nUser: ",
    "takenby": "shalini kushwah",
    "datecreated": "2024-03-20T05:54:37.47",
    "createdfrom_id": 0,
    "top_level_id": 1,   
    "oppdontaddtomailinglist": false,
    "workflow_name": "Incident Management Workflow",
    "orionacknowledgedby": 0,
    "orionacknowledgedate": "1900-01-01T00:00:00",
    "atera_alert_id": 0,
    "laststatuschangestatus": 0,
    "laststatuschangestatusdate": "1899-12-30T00:00:00",
    "meraki_device": "",
    "meraki_alert_type": "",
    "flastupdate": "2024-03-20T05:54:37.74"
    "ninja_alert_id": "",
    "ninja_device_id": 0,
    "isbillable": true,
    "itemsarebillable": true,
    "who": "shalini kushwah",
    "resourcetype_id": 0………………….
}

Get Teams

Endpoint: https://{tenant}.haloitsm.com/api/Team
Method: GET
Params:
Headers:

Key	Value
Authorization	Bearer <ACCESS_TOKEN>
Content-Type	application/json

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "guid": "5c481f56-4369-401c-a608-4b1407f63aff",
        "name": "1st Line Support",
        "sequence": 10,
        "forrequests": true,
        "foropps": false,
        "forprojects": true,
        "ticket_count": 0,
        "department_id": 3,
        "department_name": "Crest data systems - IT",
        "inactive": false,
        "override_column_id": 0,
        "teamphotopath": "",
        "hide_agents_in_tree_if_no_tickets": false,
        "use": "team"
    }
]

Performance Matrix

This performance reading is collected on a Large CE Stack with below-mentioned specifications by generating 1000 tickets at a time.

Stack Details	Size: LargeRAM: 32 GB CPU: 16 Cores
Tickets created on HaloITSM	~30 per minute

User Agent

The user-agent added in this plugin is in the following format

netskope-ce-<ce_version>-<module>-<plugin_name>-v<plugin_version>

For example:

netskope-ce-5.0.0-cto-halo-itsm-v1.0.0

Workflow

Create a HaloITSM Application.
Authenticate using Username & Password.
Configure the HaloITSM plugin
Configure a Business Rules.
Configure a Queue Configuration.
Validate the plugin.

Click play to watch a video.

Create a HaloITSM Application

Log in to the HaloITSM platform.
Go to Configuration > Integrations > HaloITSM API. Note the Tenant name shown; it will be used while configuring the HaloITSM plugin in Cloud Exchange. Click View Application.
Click New to create a new application.
Enter a name for the application, and select either Username & Password or Client ID & Secret (Services) for the Authentication Method. Make sure the Active checkbox is enabled. The Displayed Client ID will be used while authenticating the HaloITSM plugin in Cloud Exchange. Steps for both options are provided in the next two sections.

Authenticate using Username & Password

Select Username & Password for the Authentication Method.
Select the needed branding, select the Allow Agent Logins and Allow End-User Logins options, and then select an option from the Single Client Access dropdown.
Go to the Permissions tab, select the read:tickets, edit:tickets, read:customers permissions, and then click Save.
The Application is ready to use with the Username & Password authentication method.

Authenticate using Client ID and Secret (Services)

Select Client ID and Secret (Services). Copy the Client ID to use while creating the HaloITSM plugin in CE.
Click Generate to create the Client Secret, which will also be used to configure the HaloITSM plugin in CE. Copy the Client Secret. Make sure to select Client in the Login Type dropdown. Select your client.
Go to the Permissions tab, select the read:tickets, edit:tickets, read:customers permissions, and click Save.
The Application is ready to use with the Client ID & Secret (Services) authentication method.

Configure the HaloITSM Plugin

In Cloud Exchange, go to Settings > Plugins.
Search for the HaloITSM plugin and click on the HaloITSM plugin box (make sure the CTO module is enabled. If not, go to Settings > General and enable the Ticket Orchestrator module).
Enter the Configuration Name.
Adjust the Sync Interval to the appropriate value: Suggested is 5+ minutes.
Click Next.
Provide the Tenant Name. To get the tenant name and refer to the Create an application Section.
1. If on the HaloITSM platform, Username & Password was selected in the authentication method, select the same option here. Otherwise, authentication will result in failure. Enter your Client ID. To get the Client ID refer to the Create an application Section. Click Next.
  
  Provide the Username and Password that was used while authenticating the HaloITSM platform. Click Save.
2. If on the HaloITSM platform, Client ID & Secret (Services) was selected in the authentication method, select the same option here. Otherwise, authentication will result in a failure. Enter your Client ID and click Next.
  
  Enter your Client Secret. Refer to the Create an application section to know from where to get the Client ID and Client Secret. Click Save.

Configure a Ticket Orchestrator Business Rule for HaloITSM

Create a business rule based on the filters you need to generate tickets in the HaloITSM platform.

In Ticket Orchestrator, click Business Rules.
Click Create new rule.
Enter an appropriate Rule Name in the text box and build the appropriate filter query condition on the field(s) for the business rule. You can also type the query manually by pressing the Filter Query button.
Click Save.

Configure a Ticket Orchestrator Queue for HaloITSM

In Ticket Orchestrator, click Queues.
Click Add Queue Configuration.
Select the 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, which will have a team list.
Note
- If authentication of the HaloITSM plugin is done using the Username and Password authentication method, then all the teams will be displayed in the Queues dropdown including the default team.
- If authentication of the HaloITSM plugin is done using the Client Credentials authentication method, then the Default team will be listed in the Queues dropdown, because to create tickets using Client ID and Secret (Services) authentication method, Login Type should be Client. And for Client Login Type API is responding 403, hence the default team is added in Queue. If Agent is selected in Login Type, then Team API will list all the teams, but tickets won’t be created.

Add appropriate values in the Map Field section. The Provided Mapping should be visible in the ticket details created in the HaloITSM platform.

These values are supported in the Category field. These values should be provided in the text box present below the Custom Message displaying dropdown. Category will be required if set in the HaloITSM Platform. If any new category is added for category on the HaloITSM platform, then it will be the supported value.

Account Administration

Account Administration>Application Access

Account Administration>Disable Account

Account Administration>Folder Access

Account Administration>Mail Access

Account Administration>New Account

Account Administration>New Distribution Group

Account Administration>New Mailbox

Account Administration>Password Reset

Account Administration>User Termination\Leaver

Business Applications

Hardware>Desk Phone

Hardware>Desktop

Hardware>Docking Station

Hardware>Fax Machine

Hardware>Headsets

Hardware>ID Badges

Hardware>Laptop

Hardware>Mobile Device

Hardware>Monitor

Hardware>Mouse/Keyboard

Hardware>Printer

Hardware>Projector

Hardware>Scanners

Hardware>Smartphone

Hardware>Standard Mobile Phone

Infrastructure>Data Connection

Infrastructure>Riverbed

Infrastructure>Router

Infrastructure>Server

IT Security Threats>Cylance

IT Security Threats>Email Spoofing

IT Security Threats>Investigations

IT Security Threats>Malware

IT Security Threats>Phishing Email

IT Security Threats>Ransomware

IT Security Threats>Software Vunerability

IT Security Threats>Virus

Standard Applications>Adobe

Standard Applications>Adobe Writer

Standard Applications>CAD Applications

Standard Applications>Citrix

Standard Applications>Email

Standard Applications>Internet

Standard Applications>MS Office

Standard Applications>One Drive

Standard Applications>Operating System

Standard Applications>Other (Not Listed)

Standard Applications>Print Software

Standard Applications>RDS

Standard Applications>SAP

Standard Applications>SharePoint

Standard Applications>VPN Client

Telecommunications>BT Land Lines

Telecommunications>BT Mobile Services

Telecommunications>Cisco

Telecommunications>Skype for Business

These values are supported in the Impact (CFimpact) field. These values should be provided in the text box present below the Custom Message displaying dropdown. Impact will be required if required is set in the HaloITSM Platform. User needs to provide the Numeric Value: 1, 2, or 3, and it will be mapped according to these values. If any new value is added for CFImpact on the HaloITSM platform, then it will be the supported value.

1 Organization Wide

2 Multiple Users Affected

3 Single User Affected
These values are supported in the Urgency (CFurgency) field. These values should be provided in the text box present below the Custom Message displaying dropdown. Impact will be required if required is set in the HaloITSM Platform. User needs to provide the Numeric Value: 1, 2, or 3, and it will be mapped according to these values. If any new value is added for CFUrgency on the HaloITSM platform, then it will be the supported value.

1 High

2 Medium

3 Low

Click Save.
Based on the business rule(s), tickets for incoming alerts will be created automatically. To create Tickets for historical alerts, click on 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 Tickets data for those alerts.

Validate the HaloITSM Plugin

In Cloud Exchange

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

To view the list of tickets created on HaloITSM Platform, go to Tickets in Ticket Orchestrator.
You can also go to the Logging and check the logs for tickets created.
If tickets are not being created on the HaloITSM platform, you can look at the audit logs here. Apply the filter: Type any in Error.

In HaloITSM

Click on the External Link of any ticket to directly go to the newly created Jira ticket. On the HaloITSM platform, go to Incidents, select the team, and search for your ticket.

Troubleshooting

Unable to configure HaloITSM Plugin.

If you are unable to configure HaloITSM plugin, it might be due to:

Incorrect credentials.
Incorrect Tenant name.
Selected an authentication method other than the one selected in HaloITSM platform.

What to do:
Check the logs under Logging, and make sure there are no errors. If there is any error, then resolve it. It might be due to:

Incorrect credentials.
Incorrect Tenant name. To check tenant names, refer to create an application section.
Check the authentication method configured on the HaloITSM platform for a particular application.

Unable to create Tickets on HaloITSM

If you are not able to create tickets on the HaloITSM plugin, it might be due to one reasons:

Authentication methods have been updated in the HaloITSM platform.
Proper permissions are not set for the application.
It might be the case that you have made some other fields required that are not supported in the plugin.

What to do:
Check the logs under logging, and make sure there are no errors. If there is any error, then resolve it.

Make sure that the authentication method in the HaloITSM platform and in the plugin is the same.
Make sure all the needed permissions are set for the application. To check permissions, refer to the Permissions section.
Make sure that you have only the fields supported by the plugin as required and not any extra in the Ticket > Ticket Types > Incident > Field List. To check the supported fields refer Adding Queue.

Unable to see the Category, CFImpact, or CFUrgency on the HaloITSM platform.

If you are not able to see the Category, CFImpact, or CFUrgency on the ticket created on HaloITSM platform, it might be due to an incorrect value of Category, CFImapct, or CFUrgency was provided while configuring the queue.
What to do:
Check the Configure a Queue section to know the supported values.

Limitation

The Client ID and Secret (Services) authentication method is having some below-mentioned restrictions:
- If Agent is selected in Login Type, then tickets will not be created, but users will be able to see all the teams listed while configuring the queue.
- If Client is selected in Login Type, then the user will not be able to see the teams list while configuring the queue, but the tickets will be created successfully.
- Support of basic fields is provided for mapping while configuring the Queue, as the API Payload was not returning needed field values that can be used.

1	Organization Wide
2	Multiple Users Affected
3	Single User Affected

1	High
2	Medium
3	Low

HaloITSM Plugin for Ticket Orchestrator