ServiceNow v1.0.3

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: 1.0.3

Compatibility with FortiSOAR™ Versions: 4.9.0.0-708 and later

Compatibility with ServiceNow Versions: 2.1.0 and later

Release Notes for version 1.0.3

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

• Added a new playbook named 'Get ServiceNow Open Tickets'.
• Merged the functionality of the following playbooks with other playbooks: 3.2 Schedule Playbook for ServiceNow Updates and 4.2 Check Periodic Status Of ServiceNow Tickets Equal To Open. Therefore, these playbooks have been removed from Included playbooks.
• Renamed 'Check Status Of ServiceNow Tickets Equal To Closed' playbook to 'Get ServiceNow Closed Tickets'.
• Renamed the configuration parameter 'Instance' to 'Server URL'.
• Renamed the 'Create New Record operation to 'Create Record' and renamed its input parameter 'Incident Information to 'Record Information'.
• Renamed the 'Update CyOps with ServiceNow details' operation to 'Update CyOPs Record' and renamed its input parameters.
• Renamed the 'Advanced Search Query' operation to 'Advanced Search' and renamed its input parameter to 'ServiceNow ticket’s sys_id, description, and state' to 'Advanced Search Query'.
• Renamed the 'Update ServiceNow with CyOPs details' operation 'Update ServiceNow Record' and renamed its input parameters.
• Added the annotations back for the operations.

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 for the ServiceNow server. For example, https://instance.service-now.com
Username	Username to access the ServiceNow server.
Password	Password to access the ServiceNow server.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not. Defaults 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 Record	Adds a new record in the ServiceNow table that you have specified.	create_record Investigation
Search Record	Searches for a record in the ServiceNow database.	search_record Investigation
Update CyOPs Record	Updates a FortiSOAR™ record with ServiceNow ticket details. For example, this operation will update the system ID, description, and state of a ServiceNow ticket in a FortiSOAR™ record.	update_record Investigation
Advanced Search	Executes a generalized query on a specified ServiceNow table.	search_query Investigation
Update ServiceNow Record	Updates the specified ServiceNow record with the fields of the corresponding FortiSOAR™ record.	update_record Investigation

operation: Create Record

Input parameters

Parameter	Description
Table Name	The 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 ServiceNow record created.

Following image displays a sample output:

operation: Search Record

Input parameters

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

Output

A JSON output contains the detailed information about the ServiceNow ticket retrieved based on the specified parameters.

Following image displays a sample output:

operation: Update CyOPs Record

Input parameters

Parameter	Description
Update ServiceNow Ticket Details	The system ID, description, and state of a ServiceNow ticket that you want to update in the FortiSOAR™ record
ServiceNow to CyOPs Mapping	The mapping of the description and status of the ServiceNow ticket with FortiSOAR™. The description field from ServiceNow maps to the description field in FortiSOAR™. The state field from ServiceNow maps to the status field in FortiSOAR™.
Picklist Mapping	The mapping of the picklist values of the status of the ServiceNow ticket with a FortiSOAR™ record.

Output

A JSON output contains the detailed information about the specified ServiceNow ticket, including state and description, that requires to be updated in the FortiSOAR™ record.

Following image displays a sample output:

operation: Advanced Search

Input parameters

Parameter	Description
Table Name	The name of the table (in the ServiceNow database) in which you want to search for a record. For example, incident.
Advanced Search Query	The system ID, description, and state of a ServiceNow ticket. 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

A JSON output contains the detailed information about the ServiceNow ticket retrieved based on the generalized query.

Following image displays a sample output:

operation: Update ServiceNow Record

Input parameters

Parameter	Description
Table Name	The name of the table (in the ServiceNow database) that requires to be updated.
ServiceNow Ticket Details	The details of the ServiceNow ticket that requires to be updated. Details can include system ID, description, state or any other field of the ServiceNow ticket.
ServiceNow to CyOPs Mapping	The mapping of the description and status of the ServiceNow ticket with FortiSOAR™. The description field from ServiceNow maps to the description field in FortiSOAR™. The state field from ServiceNow maps to the status field in FortiSOAR™.
Picklist Mapping	The mapping of the picklist values of the status of the ServiceNow ticket with FortiSOAR™.

Output

A JSON output contains the detailed information about the ServiceNow record updated with the fields of the corresponding FortiSOAR™ record.

Following image displays a sample output:

Included playbooks

The Sample-ServiceNow-1.0.3 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 Start Playbook
• 1.2 Create Record
• 2.1 Search Record
• 2.2 Update CyOPs Record
• Advanced Search
• Create Record
• Get ServiceNow Open Tickets
• Get ServiceNow Resolved Tickets
• 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.10.2. 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 checkbox.
      
   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 checkbox.
      
   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 Editorsection.
   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.