Configuring ticket escalation with Spark

Ticket Escalation enables Spark to hand over unresolved employee conversations to the service desk by creating a ticket in the organization’s information technology service management (ITSM) system.

Spark resolves many employee issues through self-service. When an issue requires human intervention, Spark escalates the conversation using a predefined API Call that creates an ITSM ticket and preserves the conversation context.

Administrators configure Ticket Escalation to control how Spark connects to the ITSM system and what information is sent when a ticket is created.

When does Ticket Escalation occur

Spark escalates a conversation when it cannot resolve the issue autonomously, for example:

• Technical issues that require service desk support
• Questions that Spark cannot resolve
• Requests that are not yet automated

Ticket Escalation ensures these conversations are routed through existing ITSM processes and remain traceable.

How Ticket Escalation works

1. Spark identifies that the issue requires escalation.
2. The employee confirms that Spark should create a ticket.
3. Spark calls the predefined API Call and passes the conversation context.
4. The API Call creates a ticket in the ITSM system.
5. The ITSM system returns a ticket reference.
6. Then, Spark:

   • Shares the ticket reference with the employee.
   • Marks the conversation as Escalated in the Spark cockpit with ticket reference.
7. If ticket creation fails, Spark sends fallback notifications to the employee.

This process ensures continuity and allows support teams to track and follow up on the issue without losing context from the original conversation.

Prerequisites

To configure connector credentials and API Calls, you must have:

• Administrator access rights in Nexthink to configure Connector credentials and API Calls.
• Credentials created in the ITSM system, ready for Nexthink integration.

  • Ensure that the credential used has the required permission in your ITSM to read and create incidents, e.g., has the itil role.
• CSV file two-tier categorization imported from your ITSM: Spark will use it to dynamically assign categories when creating an ITSM ticket. Refer to the Upload category and sub_category step of the Integration flow on this page.
• Obtain a self-service portal URL, which Spark will use to notify employees when it cannot escalate a request.

Integrating flow

To configure Ticket Escalation, set up connector credentials and configure an API call that uses these credentials to create a ticket in the ITSM system. Then, in the Spark Ticket Escalation settings, select this API call and define which data Spark sends to the ITSM during escalation.

The following guide describes each step in detail.

1

Configure connector credentials for the ITSM system

Connector credentials define how Nexthink authenticates with the ITSM system.

Create connector credentials to your ITSM system in the Nexthink web interface. Refer to the Connector credentials for more information.

2

Configure the API Call for incident creation

The API Call defines how Nexthink will create a ticket in the ITSM system. From the Nexthink web interface:

1. Go to Administration > API Calls.
2. Click New API Call.
3. Configure the API Call by defining settings across the following tabs:

   • General tab: Define the API Call name, description, and connector credentials (configured in step 1).

   

   • Request tab: Define the request method, resource endpoint, parameters used to receive values from Spark at execution time, and the payload with dynamic parameters.

     • Under Parameters, define parameters that Spark populates dynamically during ticket escalation. The following example shows parameters used to create a ticket in ServiceNow.

       • Category (category): High-level classification of the issue identified during the conversation.
       • Subcategory (subcategory): More specific issue classification derived from the conversation context.
       • Configuration item (config_item): The affected device or configuration item associated with the issue.
       • Caller (callerId): Identifies the employee for whom the ticket is created.
       • Work notes (workNotes): Diagnostic information and additional context collected by Spark during the conversation.

       Spark assigns values to these parameters at runtime based on the conversation and any diagnostic actions performed.
     • Under HTTP call, define the payload sent to the ITSM system when Spark escalates a conversation. During ticket escalation, Spark injects parameter values into the payload by replacing placeholders with runtime values. Use {{parameter}} for dynamic values. The following example shows parameters used to create an incident in ServiceNow.

       • Method: POST
       • Resource: api/now/v1/table/incident
       • Payload:

         {
             "assignment_group": "{{assignmentGroup}}",
             "caller_id": "{{callerId}}",
             "work_notes": "{{workNotes}}",
             "short_description": "{{shortDescription}}",
             "contact_type": "{{contactType}}",
             "description": "{{description}}",
             "cmdb_ci": "{{cmdbCi}}",
             "category": "{{category}}",
             "subcategory": "{{subcategory}}"
           }
         

   • Output tab: Define the values extracted from the ITSM response and returned to Spark. Use JSONata to define how to extract the ticket details from the payload. The output must contain the following identifiers exactly as specified:

     • Ticket Unique ID: ticketId
     • Ticket Display Number: ticketNumber
4. After configuring parameters and payload, use the Test results panel to run the API Call with real data, inspect responses, and identify errors. Verify the extracted output fields in a Preview column. The test panel helps validate the configuration and reduce trial and error.

3

Upload category and sub_category

From the Nexthink web interface:

1. Go to Spark > Manage Spark > Escalation > Categorization.
2. Click Upload CSV file.

1. Choose the CSV file from your hard drive, with up to 1000 rows per file, to import it into the system.

The file must include two columns category and sub_category, with each row representing a unique issue type. Spark uses them to understand the type of issue being discussed and to classify tickets consistently during escalation.

Example:

category	sub_category
Hardware	Battery
Hardware	Keyboard
Hardware	Display
Software	OS
Software	Application
Network	WiFi
Network	VPN

This list defines the valid issue classifications that Spark can select when:

• Interpreting employee conversations
• Populating required categorization fields parameters during ticket escalation

When Spark is configured to use category and sub_category for decision-making, it determines the issue type based on the values uploaded in this list.

You can upload a category and subcategory list that is custom-defined and aligned with your ITSM taxonomy, including lists imported from different ITSM systems.

4

Configure Spark settings for ticket escalation

From the Nexthink web interface:

1. Go to Spark > Manage Spark > Escalation.
2. Select the Escalation configuration tab.
3. Select the previously configured API Call from the list.

   • Define the Parameters field used for ticket creation. These parameters determine which information Spark includes when escalating a ticket. For each parameter, select one of the following options from the drop-down list and specify how Spark should populate its value:

     • Device: Select a device property, including device custom fields. Spark passes the corresponding value from the affected device to the ITSM platform.
     • User: Select a user property, including user custom fields. Spark passes the corresponding value from the affected user to the ITSM platform.
     • Custom value: Enter a fixed value. Spark always passes this value to the ITSM platform when escalating a ticket.
     • No selection: Spark does not pass any value for this parameter.

     In the following example, Spark passes the value of the Assigned support team user custom field as the Assignment group parameter. This allows the ITSM platform to route the ticket to the appropriate support team.

   

   • Define the Ticket information that Spark displays to the employee in the chat. The available values are based on the API response configured in the Configuring ticket escalation with Spark step.

     • Displayed ticket reference: Select which value from the API response Spark displays as the ticket number.
     • Ticket link format: Configure the ticket link format to match how your ITSM system generates ticket URLs. Type {{ to insert values returned by the API response.
   • Define the Request redirection URL. This is the link to the self-service portal that Spark will give to employees when it cannot process a request on their behalf.

   

   • Send a test request to verify the integration with your ITSM system.

     • Open the test panel on the right side of the page.
     • Select a valid user and device from the drop-down lists. All dependent parameters are populated automatically based on the selected user and device.
     • Fill the remaining parameters with example values.
     • Click Run Test.
     • Review the test result displayed in the test panel. If the test is successful, verify that the ticket was created in your ITSM system.