Skip to main content
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.
  • 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)

Fields are dynamically populated based on the selected authentication type.

Advanced Configuration​

This section allows users to customize ITSM settings using YAML, including payload transformations, field mappings, severity conversions, and additional attributes. It provides step-by-step instructions for defining static fields, dynamic mappings, and severity conversions for seamless integration with ITSM systems like Jira, ServiceNow, and BMC Remedy. For details, please refer to the Advanced Configuration (YAML-based) Section.

Enabling or Disabling Ticket Actions​

In the YAML configuration, users can enable or disable specific ticket actions such as get, update, or close using the ticket_action_control section.

Default Behavior

By default, all actions listed under ticket_action_control are enabled. This means the system will perform operations like fetching ticket status automatically 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)​

Users can configure all API endpoints and HTTP methods for ticket actions using the following YAML sections:

  • request_method_map: Specifies the HTTP method (GET, POST, PUT, PATCH, DELETE) to be used for each ticket operation.
  • endpoint_map: Defines the specific API endpoint paths for operations like create, update, and close

Example:

request_method_map:
  create: "Post"
  update: "Post"
  get: "Post"
  close: "Post"
  search: "Post"

endpoint_map:
  create: ""
  status: ""
  browse: ""
  update: ""
  search: ""

Alarm State Ticket Status Mapping​

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"

Search Identifier (via YAML)​

  • To enable ticket search based on description, users can configure the search_query_template field.
  • This template defines the query parameters used for searching tickets. Currently, it supports using either the plain summary or the encoded_summary.
search_query_template: "sysparm_query=short_description={encoded_summary}&sysparm_limit=5&sysparm_fields=number,state,sys_id"
note

Use {summary} for raw text or {encoded_summary} if URL encoding is required in the query string.

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:
  1: Open
  2: Open
  3: Open
  4: Done
  6: Done
  7: Done

Ticket Status Field​

The status of each ticket may be located in different fields depending on the ITSM system being integrated. To support flexible extraction, users can specify the exact field name using YAML. This ensures smooth and accurate retrieval of the ticket status from the response payload.

ticket_status_field: "state"

Ticket ID Field​

Different ITSM systems may use various field names to represent the unique identifier of a ticket. The ticket_id_field allows users to specify the exact field (e.g., "sys_id") from which the ticket ID should be extracted, ensuring correct identification and tracking of tickets.

ticket_id_field: "sys_id"

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

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.

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 allows users to define a Python script to create custom payloads and headers. This feature is available when the configuration mode is set to Custom Configurations.

Purpose of the Script
With this script, users can:

  • Programmatically generate payloads and headers.
  • Customize message formats based on dynamic conditions.

When to Use the Payload Configuration Script?

Use the Payload Configuration Script if you need advanced logic to build the payload using data such as:

  • Preferences
  • Alert details
  • Additional metadata
  • Headers that must be appended to the existing payload

This script can extend or override the default payloads and headers defined in the YAML configuration file.

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:

  1. PAYLOAD: Dict to be sent as the request body.
  2. HEADERS: Dict used for HTTP headers.
  3. ALERT_DOC: Dict containing details of the alert.
  4. PREFERENCES: Dict of ITSM configuration values.
  5. 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": "[email protected]",
  "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.