Fortinet Document Library

Version:


Table of Contents

1.0.3
Copy Link

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:

 

Sample output of the Create Record operation

 

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:

 

Sample output of the Search Record operation

 

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:

 

Sample output of the Update CyOPs Record operation

 

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:

 

Sample output of the Advanced Search operation

 

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:

 

Sample output of the Update ServiceNow Record operation

 

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.
      Adding a ServiceNowTicketStatus picklist
    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.
      Adding a Splunk Urgency picklist
    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.
      Updating Incident module with 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.
      Updating Incident module with Create ServiceNow ticket picklist
      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.
      Updating Incident module with ServiceNow Ticket Number field
      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.
      Updating Incident module with ServiceNow Sys ID field
      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.

 

 

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:

 

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

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:

 

Sample output of the Create Record operation

 

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:

 

Sample output of the Search Record operation

 

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:

 

Sample output of the Update CyOPs Record operation

 

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:

 

Sample output of the Advanced Search operation

 

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:

 

Sample output of the Update ServiceNow Record operation

 

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.

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.
      Adding a ServiceNowTicketStatus picklist
    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.
      Adding a Splunk Urgency picklist
    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.
      Updating Incident module with 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.
      Updating Incident module with Create ServiceNow ticket picklist
      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.
      Updating Incident module with ServiceNow Ticket Number field
      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.
      Updating Incident module with ServiceNow Sys ID field
      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.