Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use.

Overview

ServiceNow aims to deliver digital workflows that create great experiences and unlock productivity for enterprise operations. The company's core business revolves around management of "incident, problem, and change".

This Integration allows customers to create incident tickets in ServiceNow straight from the Universal Controller. A typical Use Case is creating a ticket in ServiceNow in the event of a Task failure within the Universal Controller.

Version Information

Refer to Changelog for version history information.

Software Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Software Requirements for Universal Template and Universal Task

Tested with Python version 3.7.6 and 3.11.6 and with the Universal Agent bundled Python distribution.

Software Requirements for Universal Agent

Both Windows and Linux agents are supported.

• Universal Agent for Windows x64 Version 7.3.0.0 and later with Python options installed.
• Universal Agent for Linux Version 7.3.0.0 and later with Python options installed.

Software Requirements for Universal Controller

Universal Controller Version 7.3.0.0 and later.

Network and Connectivity Requirements

• Extension's Universal Agent host should be able to reach ServiceNow REST endpoints.
• When creating attachments from Task Instances, the extension's Universal Agent Host should be able to reach the Universal Controller.
• The ServiceNow Credentials provided in the ServiceNow Incident Universal Task should have sufficient permissions to invoke ServiceNow APIs and create incidents.

Supported ServiceNow Versions

This integration is tested on ServiceNow Vancouver. It should be compatible with newer versions of ServiceNow as long as ServiceNow backward compatibility is preserved.

Key Features

This Universal Extension provides the following key features:

• Actions
  • Create a ServiceNow Incident.
• Authentication
  • Authentication using ServiceNow Credentials.
  • Authentication using OAuth2
• Input/Output
  • Capability to send the output of any task instance as an incident attachment.
  • Capability to include some of the available instance fields as part of the incident attachment.

Import Universal Template

To use the Universal Template, you first must perform the following steps.

1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

2. To import the Universal Template into your Controller, follow the instructions here.

3. When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers before or after import, might affect its supportability. For more information, refer to Integration Modifications.

Configure Universal Task

For a new Universal Task, create a new task and enter the required input fields.

Input Fields

The input fields for this Universal Extension are described below.

Additional Fields (JSON) Configuration

The Additional Fields (JSON) field allows users to set values for existing ServiceNow Fields in JSON format. 

Each key in the JSON represents a column name in the Incident table. To find the correct column names, follow these steps.

• On ServiceNow platform, at the top menu click on All.
• Search for System Definition. Under System Definition select Tables.
• At the top, search for the table by entering the Table Name, which in this case it is Incident.
• Select the Incident table. A list with all the Incident table fields will appear.
• Hover on the specific field and click on the Info Icon.
• New small window will appear in which the Column name can be seen.

Example of how locating the Column name of a field looks like can be seen below.

The value for each field must be formatted according to the corresponding incident table field type and should comply with ServiceNow API requirements. Example of how the Additional Fields (JSON) field can be populated with various of table field types is shown below.

{
    "active": true,		
    "on_hold": false,	
    "opened_at": "2024-08-26 15:30:00",
    "resolved_at": "2024-08-27 10:00:00",
    "impact": 3,
    "urgency": 2,
    "priority": 3,
    "state": 1,
    "short_description": "Printer not working",
    "description": "The office printer on the 3rd floor is not responding.",
    "contact_type": "phone",
    "category": "hardware",
    "number": "INC001000",
    "reassignment_count": 1,
    "caller_id": "Lucius Bagnoli", 
    "assigned_to": "Jimmie Barninger",
    "watch_list": "Lucius Bagnoli,Jimmie Barninger",
    "work_notes": "Checked printer connection. Power seems to be the issue.",
    "comments": "User reported loud noise before printer stopped working."
  }

The following table provides more information on the example's fields.

Task Examples

Create Incident

Example of creation of an incident.

Create an Incident with an attachment from a Sibling Task

Example of creating an incident with an attachment from a sibling task within a workflow. The workflow is configured to create a ServiceNow incident when a task fails.

An example workflow where a ServiceNow Incident Universal Task follows the Failure transition of a SQL Task is provided below.

An example of a task configured to use the information from the failed Universal Task Instance as an attachment for creating a ServiceNow Incident is provided below.

Create an Incident from any Task Instance

Example of creation of an incident from any Task Instance.

Best practice to configure such a scenario within UAC is shown below.

Step 1: Create a Monitor Task that monitors for the failure of tasks by configuring Monitor Details.

Step 2: Configure the ServiceNow Incident task. The created Incident Task propagates the output of the failed Task Instance as an attachment to ServiceNow. For that, a Task Monitor trigger is required.

Step 3: Create a Task Monitor Trigger linked to the Monitor Task (on Step 1), which controls the action that needs to be taken when the monitor successfully monitors a failure, in this case, the trigger of an incident ticket configured on Step 2.

Create Incident using OAuth2 authentication

Create Incident with Additional Fields

Task Output

Exit Codes

The exit codes for this Universal Extension are described below.

Extension Output

In the context of a workflow, subsequent tasks can rely on the information provided by this integration as Extension Output.

Attribute changed is populated as follows

• true, in case a ServiceNow incident is successfully created.
• false, in case a ServiceNow incident is not successfully created.

The Extension output contains the attribute result. Attribute result contains the following sub-attributes:

An example of the Extension Output for creating a ServiceNow Incident is presented below.

{
    "exit_code": 0,
    "status_description": "SUCCESS: ServiceNow Incident Create Incident executed successfully!",
    "changed": true,
    "invocation": {
        "extension": "ue-servicenow-incident",
        "version": "2.3.0",
        "fields": {...},
    "result": {
        "code": 201,
        "ticket_number": "INC0010056",
        "sys_id": "5115d027a30f383f6df5209c5e27a117"
    }
}

STDOUT and STDERR

STDOUT and STDERR provide additional information to the User. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.

Integration Modifications

Modifications applied by users or customers before or after import might affect the supportability of this integration. The following modifications are discouraged to retain the support level for this integration.

• Python code modifications should not be done.
• Template Modifications
  • General Section
    • "Name", "Extension", "Variable Prefix", and "Icon" should not be changed.
  • Universal Template Details Section
    • "Template Type", "Agent Type", "Send Extension Variables", and "Always Cancel on Force Finish" should not be changed.
  • Result Processing Defaults Section
    • Success and Failure Exit codes should not be changed.
    • Success and Failure Output processing should not be changed.
  • Fields Restriction Section
    • Default configured values should not be changed.

Users and customers are encouraged to report defects or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents.

Changelog

ue-servicenow-incident-2.3.1 (2024-09-26)

• Fixes: Enhanced Choice fields value retrieval to handle cases where commas are part of the field values. (#42430, #123607)

ue-servicenow-incident-2.3.0 (2024-08-29)

• Enhancements: Added support for retrieving output from all output types, as well as Instance Field information and adding it to an attachment.
• Fixes: Added encoding of data that is being sent as an attachment using UTF-8 standard.

ue-servicenow-incident-2.2.0 (2024-07-19)

• Enhancements: Added support for all ServiceNow Incident fields.
• Breaking Changes: This integration is no longer importable on Universal Controller 7.2 or runnable on Agent version 7.2.

ue-servicenow-incident-2.1.0 (2024-02-15)

• Enhancements: Added support for OAuth2 authentication method
• Breaking Changes: This integration is no longer importable on Universal Controller 7.1 or runnable on Agent version 7.1.

ue-servicenow-incident-2.0.0 (2023-09-14)

• Breaking Changes: This integration is no longer importable on Universal Controller 7.0 or runnable on Agent version 7.0. (#34222)
• Fixed: Remove value validation for the "Urgency" and "Impact" Dynamic Choice Fields. (#34232)

ue-servicenow-incident-1.0.0 (2022-07-29)

• Initial Release: Basic Functionality for ServiceNow Incidents (#29442)