Version: NG-2.16

ITSM Integration

Authentication Type

Determines the authentication method for API communication. Supported options are:

No Auth: No credentials are required; no headers are sent.
Basic Auth: Requires a username and password to authenticate API requests
- Username: The account username used to authenticate the request.
- Password: Password for basic authentication.
note
For Jira configuration, the password field should be the API key.
Token: An API token is used instead of a username/password.
Cookie: Uses a session cookie after logging in.
Oauth2 – A more secure authentication method that grants access. The following details are required:
- Client ID: A unique identifier assigned to the client application by the OAuth2 provider, used to request authorization.
- Client Secret: Enter the client secret provided by your OAuth2 provider. This is essential to authenticate API requests securely and must be kept confidential.
- Token URL: This is the endpoint provided by the OAuth2 provider where the client application sends authentication requests to obtain an access token. It plays a crucial role in the OAuth2 authentication flow, enabling the exchange of client credentials for a token.
  - Example: https://dev12345.service-now.com/oauth_token.do
- Grant Type: Specifies how the application obtains access tokens.
- Scope: The scope defines the level of access granted to the client application. It specifies the resources or permissions the application can access after authentication. The scope must align with the required permissions of the ITSM system.
  - Example:
    - Useraccount
    - incident.write (Allows creating and updating incidents)
    - Incident.read (Allows fetching incident details)
- Dynamic Token: A token-based authentication mechanism specific to SMAX ITSM. The system authenticates using provided credentials and dynamically retrieves a JWT token, which is then used for all subsequent API requests.
  - Username: Login ID used to request the token
  - Password: Password used for authentication
  - Token URL: Endpoint used to generate the JWT token
note
Dynamic Token authentication is applicable only for ITSM (SMAX) integrations. It is not supported for WhatsApp authentication.

Fields are dynamically populated based on the selected authentication type.

Advanced Configuration

For advanced ITSM customizations, you can use YAML-based configurations to define how the integration behaves. This includes capabilities like payload transformations, field mappings, severity conversions, and the addition of custom attributes. The configuration allows you to set static fields, create dynamic mappings, and convert severity levels to match the requirements of your ITSM system—whether it's Jira, ServiceNow, or any custom platform. By adding specific fields in the Advanced YAML configuration, you gain finer control and flexibility, enabling the setup to align precisely with your ticketing workflows. For step-by-step guidance on implementing these settings, refer to the YAML Configuration Guidelines document.For details, please refer to the Advanced Configuration (YAML-based) Section.

Enabling or Disabling Ticket Actions

In the YAML-based configuration for ITSM integrations, users have the flexibility to control whether the system should enable or disable specific ticket actions such as get, update, or close.
This behaviour is managed using the ticket_action_control section in the YAML configuration file.

Default Behavior

By default, all actions defined in ticket_action_control are enabled, meaning the system will automatically perform operations like fetching the ticket status unless explicitly disabled.

Configuration Example

ticket_action_control:
  get: enable
  update: enable
  close: disable

Usage Details

get: enable
- Description: Actively retrieves the current status of the ticket before performing create or update operations.
get: disable
- Description: Skips the ticket status retrieval before any operation.
- Behavior: The system will proceed directly with ticket creation or update without checking the current status.
update: enable / disable
- Enables or disables updating of existing tickets.
close: enable / disable
- Enables or disables automatic ticket closure when an alert is cleared.

Endpoint Mapping and Request method (via YAML)

When integrating vuSmartMaps with an external ITSM system (like Jira, ServiceNow, etc.), each ticketing operation—such as create, update, get status, close, or search—may require:

A specific API endpoint
A specific HTTP method (GET, POST, PUT, PATCH, etc.).

Instead of hardcoding these per system, you can define them in the YAML file using:

request_method_map: Specifies which HTTP method to us
endpoint_map: Defines the URL path for each action

This provides flexibility for different platforms and allows for easy reconfiguration without modifying application code.

request_method_map

Defines which HTTP method should be used for each operation.

  request_method_map:
  create: "Post"
  update: "Patch"
  get: "Get"
  close: "Put"
  search: "Post"

endpoint_map

Defines where each API request should be sent:

  endpoint_map:
    create: "/api/v1/tickets"
    update: "/api/v1/tickets/{ticket_id}"
    status: "/api/v1/tickets/{ticket_id}"
    close: "/api/v1/tickets/{ticket_id}/close"
    search: "/api/v1/tickets/search"

note

{ticket_id} is a placeholder that will be dynamically replaced by the system with the actual ticket ID at runtime.

    endpoint_map:
    create: It defines the API endpoint required for creating a ticket
    update: It defines the API endpoint required for updating a ticket
    status: It defines the API endpoint required for getting the ticket status
    browse: It defines the API endpoint required for getting the ticket URL
    search: It defines the API endpoint required for searching the ticket based on description.

Example: Resolved Endpoints

Assume the following:

Base URL: https://itsm.example.com
Ticket ID: 12345

Operation	Method	Resolved URL
Create Ticket	Post	`https://itsm.example.com/api/v1/tickets`
Update Ticket	Put	`https://itsm.example.com/api/v1/tickets/12345`
Get Ticket Status	Get	`https://itsm.example.com/api/v1/tickets/12345`
Close Ticket	Put	`https://itsm.example.com/api/v1/tickets/12345/close`
Search Tickets	Post	`https://itsm.example.com/api/v1/tickets/search`

In some ITSM systems, the Base URL alone is sufficient, and there's no need to append an endpoint path for certain actions. In such cases, you can set the value in endpoint_map to an empty string (""). This instructs the platform to use the Base URL as-is for that specific action, ensuring it doesn't fall back to default values that might not be compatible with your setup.

Assume Base URL: https://itsm.example.com

    request\_method\_map:  
    create: "Post"  
    update: "Post"  
    get: "Post"  
    close: "Post"  
    search: "Post"  
    browse: "Post"

  endpoint\_map:  
    create: ""  
    update: ""  
    status: ""  
    browse: ""  
    search: ""  
    close: ""

Operation	Resolved URL	Method
Create	https://itsm.example.com	Post
Update	https://itsm.example.com	Post
Get ticket status	https://itsm.example.com	Post
Close	https://itsm.example.com	Post
Search	https://itsm.example.com	Post
Browse	https://itsm.example.com	Post

This informs the system to:

Use only the base URL
Avoid appending any default or fallback paths

If you omit a key in endpoint_map, the system may try to use a default value internally, which can lead to:

Incorrect API calls
Authentication errors
Ticket creation failures

Setting empty strings ensures explicit control over the integration behavior.

Default Behavior (if YAML not provided)

If not overridden via YAML, the system uses the following default values.

  DEFAULT_ENDPOINT_MAP = {
      "create": "/rest/api/create/",
      "search": "/rest/api/search",
      "status": "/rest/api/issue/{{ticket_id}}/?fields=status",
      "browse": "/browse/{{ticket_id}}",
      "close": "/rest/api/issue/{{ticket_id}}/comments",  
  }

  REQUEST_METHOD_MAP = {
    "create": "Post",
    "update": "Put",
    "close": "Put",
    "search": "Post",
    "get": "Get",
}

Base64 Ticket ID Support

In addition to the standard {ticket\_id} placeholder, you can use the {{base64(ticket\_id)}} placeholder in endpoint_map if the endpoint requires the ticket ID to be in Base64 format.
When this placeholder is detected, the system will automatically encode the ticket ID in Base64 before substituting it in the endpoint.

Example:

endpoint_map:
  create: "/api/v1/tickets"
  update: "/api/v1/tickets/{{base64(ticket_id)}}"
  status: "/api/v1/tickets/{{base64(ticket_id)}}"
  close: "/api/v1/tickets/{{base64(ticket_id)}}/close"
  search: "/api/v1/tickets/search"
  browse: "/tickets/{{base64(ticket_id)}}"

Ticket ID = 12345
Base64 Encoded = MTIzNDU=

Resolved Endpoint (Update):

https://itsm.example.com/api/v1/tickets/MTIzNDU=

Alarm State Ticket Status Mapping (via YAML)

The alarm_state_ticket_status_map allows users to define how vuSmartMaps alert states should translate into the corresponding incident state of their ITSM system. This provides flexibility to align with the specific terminology or workflow of any external ticketing platform.

Users can configure this mapping using a YAML script.
The mapping is based on internal alert lifecycle states (e.g., "Alarm New", "Alarm Update", "Alarm Clear").
Each alert state is mapped to a corresponding incident state used by the ITSM system.

Example:

alarm_state_ticket_status_map:
  "Alarm New": "New"
  "Alarm Update": "In Progress"
  "Alarm Clear": "Closing"

Default Behavior (if YAML not provided)

If not overridden via YAML, the system uses the following default values:

alarm_state_ticket_status_map:
  "Alarm New": "Alarm New"
  "Alarm Update": "Alarm Update"
  "Alarm Clear":"Alarm Clear"

Search Identifier (via YAML)

To search for existing tickets in your ITSM system using alert data (such as the alert description), you need to define how the search query should be constructed. This is done using the search_query_template field in the YAML configuration.

The search_query_template defines how the platform will query the ITSM API to locate tickets that are potentially related to an alert. You can use the following placeholders within the template:

**{summary}** – The raw alert text.
**{encoded\_summary}** – A URL-safe version of the alert text (recommended for API queries).

Example:

search_query_template:"sysparm_query=short_description={encoded_summary}&sysparm_limit=5&sysparm_fields=number,state,sys_id"4

Explanation of Parameters:

short_description={encoded_summary} → Searches for tickets where the short description matches the alert summary.
sysparm_limit=5 → Limits the number of returned results to 5.
sysparm_fields=number,state,sys_id → Returns only the specified fields from each matching ticket.

Ticket Status Map (via YAML)

The ticket_status_map allows users to define how ticket response statuses from any external ITSM system should be translated into standardized statuses. This enables seamless alignment with the specific terminology and workflow of various ticketing platforms.

Users can configure this mapping using a YAML script.
For example, external statuses such as "open", "to-do", "in-progress", or "pending" can all be mapped to a unified internal status like "Open". Similarly, statuses like "closed" or "cancelled" can be mapped to "Done".
This mapping ensures that each alert state is appropriately associated with a corresponding ticket status from the ITSM system.

Example:

ticket_status_map:
Open
Open
Open
Done
Done
Done

Let’s say the ITSM system uses numeric codes to represent ticket statuses. In such cases, you can use a status mapping to instruct vuSmartMaps how to interpret these codes:

If the ticket status is 1, 2, or 3 → treat it as Open.
If the ticket status is 4, 6, or 7 → treat it as Done.

Ticket Status Field

Different ITSM platforms (such as Jira, ServiceNow, etc.) may return the ticket status in different fields within their API responses. To ensure accurate extraction, you can use the ticket_status_field in the YAML configuration to explicitly specify which field contains the status for vuSmartMaps.

Example Configuration:

ticket_status_field: "state"

This means vuSmartMaps will extract the ticket status from the state field in the ITSM API response.

Example API Response

{
  "number": "INC123456",
  "short_description": "High CPU usage alert",
  "state": "In Progress",
  "assigned_to": "John Doe"
}

From the above response, vuSmartMaps will read the value "In Progress" from the "state" field because that’s the field you’ve configured.

note

Different ITSM systems may return the ticket status under various field names, such as "status", "incident_state", "ticketStatus", etc.
By specifying the ticket_status_field in the YAML configuration, you ensure that the platform always knows exactly where to look—regardless of the ITSM system's structure.
If this field is not explicitly defined, "state" will be used as the default.

Ticket ID Field

Different ITSM systems may use various field names to represent a ticket’s unique identifier. To ensure accurate tracking and referencing, you can explicitly configure which field vuSmartMaps should use to extract the ticket ID.

Configuration

Use the ticket_id_field key in your YAML configuration to specify the correct field:

ticket_id_field: "sys_id"

note

If this field is not configured, vuSmartMaps will default to using "id".

Example API Response:

{
  "number": "INC987654",
  "sys_id": "abc123xyz",
  "short_description": "Disk space warning"
}

In this example, vuSmartMaps will extract "abc123xyz" as the ticket ID from the sys_id field.

Search Payload Customisation

ITSM supports customisable search payload, allowing users to modify the default search criteria when searching for tickets. This gives flexibility to define specific fields or query conditions according to business needs.
By default, ITSM provides a standard search payload. Users can override or extend this default behaviour by defining a SEARCH_PAYLOAD dictionary in the configuration script.

SEARCH_PAYLOAD = {
    "jql": 'project="ABC" AND status="Open"',
    "fieldsByKeys": False,
    "fields": ["summary", "status", "assignee", "description", "created"],
    "maxResults": 50
}

Default Search Payload

Jira:

default_search_payload = {
            "jql": jql_query,
            "fieldsByKeys": False,
            "fields": ["summary", "status", "assignee", "description",          "created"],
            "nextPageToken": None,
            "maxResults": 100,
        }

Service Now:

{"query": self.search_query}

Severity Map

The severity_map defines how alert severity levels (e.g., "critical", "warning") should be translated into numerical or system-specific severity codes expected by the ITSM platform. This allows consistent mapping of alert severities to the correct priority or impact level used in external systems.

Example:

severity_map:
  "critical": 1
  "error": 2
  "warning": 3
  "information": 4

This configuration tells the system to:

Map "critical" alerts to severity level 1
Map "warning" alerts to severity level 3

Default Behavior

If not explicitly configured, the system uses the following default mapping:

severity_map:
  "critical": "critical"
  "error": "error"
  "warning": "warning"
  "information": "information"

Custom Headers

Custom headers can be added using the custom_headers section. If users have any specific or custom headers required by their ITSM system, they can define them here.

custom_headers: 
  int-log-id: admin
  key: 2025280216-8e24122f-64e4-4ba2-abf3-56148b329606
  token: 2025280216-095a77cf-ffdf-445a-a968-5552b5813b84

Default Payload Configuration

This section provides the default payloads for Jira and ServiceNow, which serve as the base structure for creating tickets. Users can modify, extend, or override these defaults using YAML-based configurations to adjust field mappings, transformations, and additional attributes as needed. For more details on creating the payload configuration script, refer to Creating Payload Configuration Script) Section.

Here’s your starting point! Use these default payloads for Jira and ServiceNow as-is or customize them with YAML or Python—it’s your call!

Jira Default Payload Configuration

{
  "fields": {
    "project": {
      "id": 1001
    },
    "issuetype": {
      "id": 3
    },
    "summary": "Default Issue Summary",
    "priority": {
      "name": "Low"
    },
    "description": {
      "version": 1,
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Default issue description. Modify this with actual details."
            }
          ]
        }
      ]
    }
  }
}

ServiceNow Default Payload Configuration

{
  "severity": 2,
  "urgency": 2,
  "impact": 2,
  "priority": 3,
  "description": "Testing Memory usage",
  "active": True,
  "node": "server-2",
  "short_description": "test purposes for host:server-2",
  "opened_at": "2025-03-05 17:44:01",
  "sys_created_on": "2025-03-05 17:44:01",
  "correlation_id": "2025Mar03-46e6ff",
  "source": "VuNet Systems",
  "company": "VuNet Systems",
  "type": "test purposes",
  "cmdb_id": "",
  "incident_state": "1",
  "state": "1",
  "metric_name": "300"
}

Creating Payload Configuration Script

The Payload Configuration Script enables users to define a Python-based script for generating custom payloads, headers, and even response mappings when interacting with external ITSM systems.
This is especially useful when the Configuration Mode is set to Custom Configurations or when the selected ITSM Type is Custom ITSM.

When to Use the Payload Configuration Script?

You need advanced logic to dynamically build the payload using alert details, preferences, or any additional data.
You want to append or modify fields in the default payload or headers defined in the YAML configuration.
You are using Custom ITSM, and you want to handle and transform the response structure before using it internally.

Time to get creative! This script gives you full control over ITSM integration—custom headers, field mapping, alert logic—your Python skills make it happen.

Writing the Script

Prerequisites
To write and understand this script, the following knowledge is required:

Basic Python (variables, dictionaries, lists, loops, functions)
Familiarity with ITSM and alert configurations

Script Requirements

The script must be written in Python with proper indentation for clarity and maintainability.
No imports are necessary — all required libraries are pre-supported.

Accessing Data in the Script

The script can access the following dynamic objects to generate payloads and headers:

Available Objects

You can access and manipulate the following dictionaries in your script:

PAYLOAD: Dict to be sent as the request body.
HEADERS: Dict used for HTTP headers.
ALERT_DOC: Dict containing details of the alert.
PREFERENCES: Dict of ITSM configuration values.
TICKET_INFO / COMPLETE_TICKET_RESPONSE (Optional): Dict containing ticket response when using Custom ITSM.

Preferences Contains ITSM configuration details:

{
  "itsm_type": "service_now",
  "configuration_mode": "custom_configuration",
  "auth_type": "basic_auth",
  "username": "test@vunetsystem.com",
  "password": "Password",
  "config_yaml": " ",
  "cmdb_id": "",
  "base_url": "https://vunetsystems.com",
  "custom_script": " "
}

Alert Document Includes information about the alert that triggered the API call:

{
  "Alert-Rule-Name": "High_CPU_Usage_Alert",
  "severity": "critical",
  "description": "CPU usage exceeded 90%.",
  "timestamp": "2023-10-03T09:15:00.000Z",
  "alert_id": "9876521",
  "Enterprise Name": "YourCompany Inc."
}

Sample Script

Below is a sample script that generates payloads and headers based on alert severity:

# --------------------------------
# Default Script Template
# --------------------------------
# Use this script to modify PAYLOAD and HEADERS as needed.

# Common variables available:
# - PAYLOAD: Dictionary to be sent in the request body
# - HEADERS: Dictionary for HTTP headers
# - ALERT_DOC: Dictionary containing alert information
# - PREFERENCES: Dictionary containing ITSM configuration and preferences

# Example usage:
# Modify simple fields:
# PAYLOAD["status"] = ALERT_DOC.get("status", "default_status")
# PAYLOAD["source"] = "vumsart"
# PAYLOAD["name"] = PREFERENCES["username"]
# HEADERS["Authorization"] = "Bearer <your_token_here>"

# Safely add or update a nested field in PAYLOAD:
# if "code" not in PAYLOAD:
#     PAYLOAD["code"] = {}
# PAYLOAD["code"]["id"] = "123"

# OR using one-liner:
# PAYLOAD.setdefault("code", {})["id"] = "123"

# Change the timestamp field to current IST time:
# PAYLOAD["timestamp"] = datetime.datetime.now(
#     datetime.timezone(datetime.timedelta(hours=5, minutes=30))
# ).isoformat()

Response Transformation (Custom ITSM Only)

When using Custom ITSM, users can also define how to parse and transform the response data by assigning a dictionary to the RESPONSE variable:

# Handle response transformation
response_data = TICKET_INFO or COMPLETE_TICKET_RESPONSE or {}

# Support both list and dict in 'result'
result_data = response_data.get("result", response_data)
if isinstance(result_data, list) and result_data:
    result_data = result_data[0]  # Take the first ticket if it's a list
RESPONSE = {
    "sys_id": result_data.get("sys_id", default_na),
    "ticket_number": result_data.get("number", default_na),
    "state": result_data.get("state", default_na)
}

Key Considerations

Proper Indentation: Python requires correct indentation. Syntax validation is not supported, so ensure the formatting is correct.
Testing the Script: Test the script locally using a Python IDE (like VS Code or PyCharm) before pasting it into the configuration editor.
No Imports Required: All required libraries are already supported.

FAQs

What is the process for configuring vuSmartMaps with an organization's ITSM system?

Navigate to ITSM Configurations. Select the ITSM type (e.g., Jira, ServiceNow), enter credentials, server URLs, and use the Test button to validate.

What should I do if my ITSM configuration stops working?

First, review your credentials and instance URL. Re-authenticate if needed and run a test connection in ITSM Configurations.

How does advanced YAML configuration enhance ITSM integration?

You can map custom fields, statuses, and endpoints via YAML using request_method_map, endpoint_map, and ticket_status_map. This is essential for integrating with custom workflows in Jira or ServiceNow.

Authentication Type​

Advanced Configuration​

Enabling or Disabling Ticket Actions​

Endpoint Mapping and Request method (via YAML)​

Default Behavior (if YAML not provided)​

Base64 Ticket ID Support​

Alarm State Ticket Status Mapping (via YAML)​

Default Behavior (if YAML not provided)​

Search Identifier (via YAML)​

Ticket Status Map (via YAML)​

Ticket Status Field​

Ticket ID Field​

Search Payload Customisation​

Default Search Payload​

Severity Map​

Custom Headers​

Default Payload Configuration​

Jira Default Payload Configuration​

ServiceNow Default Payload Configuration​

Creating Payload Configuration Script​

Writing the Script​

Accessing Data in the Script​

Sample Script​

Response Transformation (Custom ITSM Only)​

Key Considerations​

FAQs​

Authentication Type

Advanced Configuration

Enabling or Disabling Ticket Actions

Endpoint Mapping and Request method (via YAML)

Default Behavior (if YAML not provided)

Base64 Ticket ID Support

Alarm State Ticket Status Mapping (via YAML)

Default Behavior (if YAML not provided)

Search Identifier (via YAML)

Ticket Status Map (via YAML)

Ticket Status Field

Ticket ID Field

Search Payload Customisation

Default Search Payload

Severity Map

Custom Headers

Default Payload Configuration

Jira Default Payload Configuration

ServiceNow Default Payload Configuration

Creating Payload Configuration Script

Writing the Script

Accessing Data in the Script

Sample Script

Response Transformation (Custom ITSM Only)

Key Considerations

FAQs