ServiceNow v2.0.0

About the connector

ServiceNow provides intelligent and automated workflows across the enterprise. It supports real-time communication, collaboration, and resource sharing across various functions.

This document provides information about the ServiceNow connector, which facilitates automated interactions, with a ServiceNow server using FortiSOAR™ playbooks. Add the ServiceNow connector as a step in FortiSOAR™ playbooks and perform automated operations, such as automatically adding a new incident record in ServiceNow tables and searching and retrieving information about ServiceNow records.

Version information

Connector Version: 2.0.0

FortiSOAR™ Version Tested on: 4.11.0.-1161

ServiceNow Version Tested on : 2.1.0

Authored By: Fortinet

Certified: Yes

Release Notes for version 2.0.0

Following changes have been made to the ServiceNow Connector in version 2.0.0:

• Added the following new operations and sample playbooks:
  • Create Incident
  • Get Users
  • Get Assignment Groups
  • Update ServiceNow Incident
  • Add Item to Cart
  • Get Items
  • Get Cart
  • Get Catalogs
  • Get Categories for Catalog
  • Update Cart Item
  • Delete Cart Item
• Removed the Update CyOPs Record Update CyOPs Record operation.
• Renamed the following operations:
  • Create Record operation to Create Table Record
  • Update ServiceNow Record to Update ServiceNow Table Record
  • Search Record to Search Table Record
    

Installing the connector

For the procedure to install a connector, click here.

Prerequisites to configuring the connector

• You must have the URL of ServiceNow server to which you will connect and perform the automated operations and credentials to access that server.
• To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, select the ServiceNow connector and click Configure to configure the following parameters:

Parameter	Description
Server URL	FQDN or IP of the ServiceNow server to which you will connect and perform automated operations. For example, https://instance.service-now.com
Username	Username to access the ServiceNow server to which you will connect and perform automated operations.
Password	Password to access the ServiceNow server to which you will connect and perform automated operations.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not. By default, this is set to True.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

Function	Description	Annotation and Category
Create Table Record	Adds a new record in the ServiceNow table that you have specified.	create_record Investigation
Create Incident	Adds a new incident record in ServiceNow based on the input parameters you have specified.	create_incident Investigation
Get Users	Retrieves a list of users and their details from ServiceNow based on the response fields you have specified.	get_users Investigation
Get Assignment Groups	Retrieves a list and details of all existing assignments groups from ServiceNow.	get_assignment_group Investigation
Search Table Record	Searches for a record in ServiceNow based on the table name and column name that you have specified	search_record Investigation
Advanced Search	Executes a generalized query on the ServiceNow table that you have specified to search for a record in ServiceNow.	search_query Investigation
Update ServiceNow Table Record	Updates a record in the ServiceNow table based on the Sys ID of the table record and other input parameters you have specified.	update_record Investigation
Update ServiceNow Incident	Updates an incident ServiceNow table based on the Sys ID of the incident and other input parameters you have specified.	update_record Investigation
Add Item to Cart	Adds an item to the cart and submits the order on ServiceNow.	add_item_to_cart Investigation
Get Items	Retrieves a list of all existing catalogs and a list and details of all items that are contained in each catalog from ServiceNow. You can optionally specify the Sys ID of the item to retrieve details only for a specific item.	get_items Investigation
Get Cart	Retrieves a default list of all existing cart contents, cart details, and price from ServiceNow.	get_cart Investigation
Get Catalogs	Retrieves a list and details of catalogs to which the user has access from ServiceNow. You can optionally specify the Sys ID of the catalog to retrieve details only for a specific catalog.	get_catalogs Investigation
Get Catalog Categories	Retrieves a list and details of all existing categories or the list and details of categories for a specified catalog from ServiceNow based on the Sys ID of the catalog you have specified.	get_categories_for catalog Investigation
Update Cart Item	Updates an item in a cart in ServiceNow based on the Cart Item ID and other input parameters you have specified.	update_cart_item Investigation
Delete Cart Item	Deletes an item from a cart in ServiceNow based on the Cart Item ID you have specified.	delete_cart_item Investigation

operation: Create Table Record

Input parameters

Parameter	Description
Table Name	Name of the table (in the ServiceNow database) in which you want to create the record. For example, incident.
Record Information	Map the record field that is present in FortiSOAR™ to the ServiceNow record field stored in the dictionary. You can pass this information to the ServiceNow record field using dynamic variables. For example, Table Name: incident Record Information: {"short_description": "QRadar Offense", "urgency": "2", "impact": "2"}

Output

The JSON output contains the ID and the URL of the record added to the specified ServiceNow table.

Following image displays a sample output:

operation: Create Incident

Input parameters

Parameter	Description
Caller	Name of the caller (in the ServiceNow database) details of whom you can retrieve using the Get Users operation.
Short Description	Short description of the incident that you want to create in ServiceNow.
Description	(Optional) Description of the incident that you want to create in ServiceNow.
Location	(Optional) Location of the incident that you want to create in ServiceNow.
Category	(Optional) Category of the incident that you want to create in ServiceNow. You can specify one of the following categories: Inquiry/Help, Software, Hardware, Network, or Database.
Severity	(Optional) Severity of the incident that you want to create in ServiceNow. You can specify one of the following severities: 1-High, 2-Medium, or 3-Low.
Urgency	(Optional) Urgency of the incident that you want to create in ServiceNow. You can specify one of the following urgencies: 1-High, 2-Medium, or 3-Low.
State	(Optional) State of the incident that you want to create in ServiceNow. You can specify one of the following states: New, In Progress, On Hold, Resolved, Closed, or Canceled.
Impact	(Optional) Impact of the incident that you want to create in ServiceNow. You can specify one of the following impacts: 1-High, 2-Medium, or 3-Low.
Work Notes	(Optional) Work Notes of the incident that you want to create in ServiceNow.
Assigned To	(Optional) Name of the user (in the ServiceNow database) to whom you want to assign this incident. You can retrieve user details using the Get Users operation.
Assignment Group	(Optional) Name of the assignment group (in the ServiceNow database) to which you want to assign this incident. You can retrieve assignment group details using the Get Assignment Group operation.
Other Fields	(Optional) JSON field provided to enable you to enter other fields while creating an incident in ServiceNow

Output

The JSON output contains the ID and the other details of the created ServiceNow Incident.

Following image displays a sample output:

operation: Get Users

Input parameters

Parameter	Description
Response Fields	Response keys based on which you want to retrieve users from ServiceNow. You can select multiple response fields.

Output

The JSON output contains the detailed information about ServiceNow users retrieved based on the response fields you have specified.

Following image displays a sample output:

operation: Get Assignment Groups

Input parameters

None.

Output

A JSON output contains the detailed information about all existing ServiceNow assignment groups.

Following image displays a sample output:

operation: Search Table Record

Input parameters

Parameter	Description
Table Name	Name of the table (in the ServiceNow database) in which you want to search for a record.
Column Name	Key of the record that you want to search in the ServiceNow table. For example, incident.
Value	Value of the record that you want to search in the ServiceNow table. For example, Incident ID.

Output

The JSON output contains the detailed information about ServiceNow table record based on the table name, column name, and value that you have specified.

Following image displays a sample output:

operation: Advanced Search

Input parameters

Parameter	Description
Table Name	Name of the table (in the ServiceNow database) in which you want to search for a record. For example, incident.
Advanced Search Query	System ID, description, and state of a ServiceNow record. Using these parameters, create a generalized query to search for multiple fields in ServiceNow. For example, Table Name: incident Record Information: {"category=inquiry&number=INC0000059"}

Output

The JSON output contains the detailed information about the ServiceNow record retrieved based on the generalized query.

Following image displays a sample output:

operation: Update ServiceNow Table Record

Input parameters

Parameter	Description
Table Name	Name of the table (in the ServiceNow database) that you want to update.
Sys ID	System ID of the ServiceNow table record that you want to update.
Description	(Optional) Description that you want to update for the ServiceNow table record.
Other Fields	(Optional) JSON field provided to enable you to enter other fields while updating a table record in ServiceNow

Output

The JSON output contains the detailed information of the table record updated in ServiceNow based on the input parameters you have specified.

Following image displays a sample output:

operation: Update ServiceNow Incident

Input parameters

Parameter	Description
Sys ID	System ID of the ServiceNow incident that you want to update. The system ID for an incident is generated when you create an incident in ServiceNow.
State	(Optional) State of the incident that you want to update in ServiceNow. You can specify one of the following states: New, In Progress, On Hold, Resolved, Closed, or Canceled.
Severity	(Optional) Severity of the incident that you want to update in ServiceNow. You can specify one of the following severities: 1-High, 2-Medium, or 3-Low.
Description	(Optional) Description that you want to update for the ServiceNow incident.
Work Notes	(Optional) Work notes that you want to update for the ServiceNow incident.
Other Fields	(Optional) JSON field provided to enable you to enter other fields while updating an incident in ServiceNow

Output

The JSON output contains the detailed information of the incident record updated in ServiceNow based on the input parameters you have specified.

Following image displays a sample output:

operation: Add Item to Cart

Input parameters

Parameter	Description
Catalog Item ID	System ID of the item that you want to add to your cart.
Extra Variables	(Optional) JSON field provided to enable you to enter other fields while adding an item to a cart.
Submit Order	Select the checkbox to submit the order on ServiceNow. By default, this is set to False.

Output

The JSON output contains the information of the cart and the item added into that cart in ServiceNow.

Following image displays a sample output:

operation: Get Items

Input parameters

Parameter	Description
Item Sys ID	(Optional) System ID of the item whose details you want to retrieve from ServiceNow.

Output

A JSON output contains a list of all existing catalogs and a list and details of all items that are contained in each catalog retrieved from ServiceNow. If you have specified the system ID of the item, then this operation retrieves the details only for a specific item from ServiceNow.

Following image displays a sample output:

operation: Get Cart

Input parameters

None.

Output

A JSON output contains the default list of all existing cart contents, cart details, and price retrieved from ServiceNow.

Following image displays a sample output:

operation: Get Catalogs

Input parameters

Parameter	Description
Sys ID	(Optional) System ID of the catalog whose details you want to retrieve from ServiceNow.

Output

The JSON output contains a list and details of all existing catalogs to which the user has access retrieved from ServiceNow. If you have specified the system ID of the catalog, then this operation retrieves the details only for the specified catalog from ServiceNow.

Following image displays a sample output:

operation: Get Catalog Categories

Input parameters

Parameter	Description
Sys ID	(Optional) System ID of the catalog whose categories you want to retrieve from ServiceNow.

Output

The JSON output contains a list of all a list and details of all existing catalog categories retrieved from ServiceNow. If you have specified the system ID of the catalog, then this operation retrieves the category details only for the specified catalog from ServiceNow.

Following image displays a sample output:

operation: Update Cart Item

Input parameters

Parameter	Description
Cart Item ID	System ID of the item that you want to update in your cart.
Other Fields	(Optional) JSON field provided to enable you to enter other fields while updating an item to a cart.

Output

The JSON output contains the information updated cart item retrieved from ServiceNow.

Following image displays a sample output:

operation: Delete Cart Item

Input parameters

Parameter	Description
Cart Item ID	(Optional) System ID of the item that you want to delete from your cart.

Output

The JSON output returns an empty response.

Following image displays a sample output:

Included playbooks

The Sample-ServiceNow-2.0.0 playbook collection comes bundled with the ServiceNow connector. This playbook contains steps using which you can perform all supported actions.

Note: The ServiceNow playbooks are compatible with FortiSOAR™ 4.10.2 and later since they include Schedules module and scheduling capability that was enhanced in FortiSOAR™ 4.10.2. Periodic playbook such as 'Get ServiceNow Open Tickets' use the Schedules module in FortiSOAR™ for adding the scheduling capability. For information on Schedules module, see the Schedules topic in the FortiSOAR™ documentation.

You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the ServiceNow connector.

• 1.1 Create Record
• 2.1 Search Record: This playbook is triggered using the Schedules module. Therefore, to run this playbook you must create a schedule record and trigger.
• 2.2 Update CyOPs Record
• Add Item to Cart
• Advanced Search
• Create Incident
• Create Record
• Delete Cart Item
• Get Assignment Groups
• Get Cart
• Get Catalog Categories
• Get Catalogs
• Get Items
• Get ServiceNow Open Tickets
• Get ServiceNow Resolved Tickets
• Get Users
• Update Cart Item
• Update ServiceNow Incident
• Update ServiceNow Record

You must update FortiSOAR™ Incidents module to add the appropriate picklists and text fields and map the Status, Ticket Number and SysID of the ServiceNow incident to the equivalent fields in the FortiSOAR™ modules, see the Updating the FortiSOAR™ modules section. This ensures that when the Status, Ticket Number or SysID of a ServiceNow incident is updated, the corresponding incident gets updated in the FortiSOAR™ Incidents module using the included playbooks.

Note: By default, playbooks that perform bi-directional updates are in the inactive state, and therefore you must activate the playbooks to validate the bidirectional update. Once the integration is working, it is recommended that you create a clone of the included playbooks in a new playbook collection and customize them as per your need and deactivate or delete the samples as they might be overwritten during the connector updates.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

Updating the FortiSOAR™ modules

Note: This procedure assumes that you are using FortiSOAR™ version 4.11.0. If you are using a different version of FortiSOAR™, such as FortiSOAR™ 4.9, then it is possible that the FortiSOAR™ UI navigation is different. Refer to the FortiSOAR™ documentation of that particular version for details about FortiSOAR™ navigation.

Perform the following steps to add the Status, Ticket Number and SysID fields to the FortiSOAR™ Incidents modules:

1. Log on to FortiSOAR™ as an administrator.
2. To open the Picklist Editor and create a picklist named ServiceNowTicketStatus, click Settings and in the Application Editor section, and click Picklists:
   1. In the Title field, type ServiceNowTicketStatus.
   2. Add status in the following order: New, In Progress, On Hold, Resolved, Closed, and Cancelled.
   3. Clear the Assign colors check box.
      
   4. Click Save.
3. Create another picklist named CreateServiceNowTicket as follows:
   1. In the Title field, type CreateServiceNowTicket.
   2. Add values in the following order: Yes and No.
   3. Clear the Assign colors check box.
      
   4. Click Save.
4. Update the Incidents Module as follows:
   1. To open the Module Editor, click Settings and then click Modules in the Application Editor section.
   2. On the Modules page, from the Select a module to edit or create a new module drop-down list, select Incidents.
   3. Click the Fields Editor tab.
   4. To add the ServiceNow ticket status picklist, click the + (Add Field) icon and add a new field with the following properties:
      In the Field Type field, select Picklist.
      From the Picklist drop-down list, select ServiceNowTicketStatus.
      In the Name field, type servicenowTicketStatus.
      In the Singular Name field, type ServiceNow Ticket Status.
      
      Click Apply.
   5. To add the Create ServiceNow ticket picklist, click the + (Add Field) icon and add a new field with the following properties:
      In the Field Type field, select Picklist.
      From the Picklist drop-down list, select CreateServiceNowTicket.
      In the Name field, type createServicenowTicket.
      In the Singular Name field, type Create ServiceNow Ticket.
      
      Click Apply.
   6. To add the ServiceNow Ticket Number to the Incidents module, click the + (Add Field) icon and add a new field with the following properties:
      In the Field Type field, select Text Field.
      In the Name field, type snTicketNumber.
      In the Singular Name field, type ServiceNow Ticket Number.
      Select the Searchable checkbox.
      
      Click Apply.
   7. To add the ServiceNow SysID to the Incidents module, click the + (Add Field) icon and add a new field with the following properties:
      In the Field Type field, select Text Field.
      In the Name field, type snSysid.
      In the Singular Name field, type ServiceNow SysID.
      Select the Searchable checkbox.
      
      Click Apply and Save.
5. Once you have completed updating all the FortiSOAR™ modules, you must publish the module to enforce the changes. Click Publish All Modules and click OK to publish the modules.