Fortinet Document Library

Version:


Table of Contents

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

FortiSOAR™ Version Tested on: 6.4.0-1555

ServiceNow Version Tested on : 2.1.0

Authored By: Fortinet

Certified: Yes

Release Notes for version 3.0.0

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

  • Added support for OAuth Authentication for ServiceNow. To support OAuth Authentication the following new configuration parameters have been added:
    • Client ID
    • Client Secret

Getting the Client ID and Client Secret from ServiceNow

To support OAuth Authentication for ServiceNow, you need to get Client ID and Client Secret from ServiceNow. To get the Client ID and Client Secret, open ServiceNow and search for OAuth in the ServiceNow navigation. Then, in the System OAuth menu, click Application Registry to create an entry for OAuth as displayed in the following image:

After creating the application registry for OAuth you will get the Client ID and the Client Secret.

Data Ingestion support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling incidents from ServiceNow. The Data Ingestion Wizard pulls "events" from ServiceNow and creates "alerts" in FortiSOAR™.

For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation. The following playbooks to support data ingestion:

  • > ServiceNow > Create Incident
  • > ServiceNow > Fetch
  • ServiceNow > Ingest
  • >>ServiceNow > Init Macros
  • ServiceNow On Incident Update

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-servicenow

Prerequisites to configuring the connector

  • You must have the FQDN or IP address of ServiceNow server to which you will connect and perform the automated operations and credentials (Username-Password pair) 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, click the ServiceNow connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

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.
Client ID Auto-generated unique ID of the client application that is requesting the access token.
Note: For the process to get the Client ID and Client Secret, see the Getting the Client ID and Client Secret from ServiceNow section. 
Client Secret Shared secret string that the instance and the OAuth application use to authorize communications between each other.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.

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 version 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, column name and value, and other input parameters 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
Get Attachments Retrieves attachments from a specific table in ServiceNow based on the system ID of the table you have specified. get_attachments
Investigation
Download File Downloads a specific file from ServiceNow and adds it in the FortiSOAR™ "Attachments" module based on the system ID of the file you have specified. download_file
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.

The output contains the following populated JSON schema:
{
     "result": {
         "order": "",
         "made_sla": "",
         "close_notes": "",
         "business_duration": "",
         "opened_at": "",
         "comments": "",
         "closed_by": "",
         "severity": "",
         "description": "",
         "watch_list": "",
         "resolved_by": "",
         "contact_type": "",
         "additional_assignee_list": "",
         "opened_by": {
             "value": "",
             "link": ""
         },
         "sys_mod_count": "",
         "number": "",
         "hold_reason": "",
         "correlation_id": "",
         "reopen_count": "",
         "sys_created_on": "",
         "caller_id": "",
         "escalation": "",
         "group_list": "",
         "incident_state": "",
         "sys_updated_by": "",
         "active": "",
         "subcategory": "",
         "state": "",
         "child_incidents": "",
         "work_notes_list": "",
         "follow_up": "",
         "activity_due": "",
         "problem_id": "",
         "sys_tags": "",
         "short_description": "",
         "category": "",
         "upon_reject": "",
         "assignment_group": "",
         "sys_created_by": "",
         "business_stc": "",
         "comments_and_work_notes": "",
         "due_date": "",
         "closed_at": "",
         "assigned_to": "",
         "expected_start": "",
         "work_end": "",
         "correlation_display": "",
         "sys_domain": {
             "value": "",
             "link": ""
         },
         "resolved_at": "",
         "approval": "",
         "close_code": "",
         "sys_updated_on": "",
         "rfc": "",
         "parent_incident": "",
         "caused_by": "",
         "upon_approval": "",
         "location": "",
         "sys_class_name": "",
         "user_input": "",
         "time_worked": "",
         "calendar_stc": "",
         "priority": "",
         "approval_history": "",
         "knowledge": "",
         "sys_domain_path": "",
         "notify": "",
         "business_service": "",
         "approval_set": "",
         "work_start": "",
         "sys_id": "",
         "impact": "",
         "parent": "",
         "sla_due": "",
         "company": "",
         "urgency": "",
         "cmdb_ci": "",
         "reassignment_count": "",
         "delivery_task": "",
         "work_notes": "",
         "calendar_duration": "",
         "delivery_plan": ""
     }
}

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.

The output contains the following populated JSON schema:
{
     "result": {
         "order": "",
         "made_sla": "",
         "close_notes": "",
         "business_duration": "",
         "opened_at": "",
         "comments": "",
         "closed_by": "",
         "severity": "",
         "description": "",
         "watch_list": "",
         "resolved_by": "",
         "contact_type": "",
         "additional_assignee_list": "",
         "opened_by": {
             "value": "",
             "link": ""
         },
         "sys_mod_count": "",
         "number": "",
         "hold_reason": "",
         "correlation_id": "",
         "reopen_count": "",
         "sys_created_on": "",
         "caller_id": "",
         "escalation": "",
         "group_list": "",
         "incident_state": "",
         "sys_updated_by": "",
         "active": "",
         "subcategory": "",
         "state": "",
         "child_incidents": "",
         "work_notes_list": "",
         "follow_up": "",
         "activity_due": "",
         "problem_id": "",
         "sys_tags": "",
         "short_description": "",
         "category": "",
         "upon_reject": "",
         "assignment_group": {
             "value": "",
             "link": ""
         },
         "sys_created_by": "",
         "business_stc": "",
         "comments_and_work_notes": "",
         "due_date": "",
         "closed_at": "",
         "assigned_to": {
             "value": "",
             "link": ""
         },
         "expected_start": "",
         "work_end": "",
         "correlation_display": "",
         "sys_domain": {
             "value": "",
             "link": ""
         },
         "resolved_at": "",
         "approval": "",
         "close_code": "",
         "sys_updated_on": "",
         "rfc": "",
         "parent_incident": "",
         "caused_by": "",
         "upon_approval": "",
         "location": {
             "value": "",
             "link": ""
         },
         "sys_class_name": "",
         "user_input": "",
         "time_worked": "",
         "calendar_stc": "",
         "priority": "",
         "approval_history": "",
         "knowledge": "",
         "sys_domain_path": "",
         "notify": "",
         "business_service": "",
         "approval_set": "",
         "work_start": "",
         "sys_id": "",
         "impact": "",
         "parent": "",
         "sla_due": "",
         "company": "",
         "urgency": "",
         "cmdb_ci": "",
         "reassignment_count": "",
         "delivery_task": "",
         "work_notes": "",
         "calendar_duration": "",
         "delivery_plan": ""
     }
}

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 detailed information about ServiceNow users retrieved based on the response fields you have specified.

The output contains the following populated JSON schema:
{
     "result": [
         {
             "default_perspective": "",
             "calendar_integration": "",
             "last_login": "",
             "cost_center": {
                 "value": "",
                 "link": ""
             },
             "introduction": "",
             "sys_updated_by": "",
             "roles": "",
             "country": "",
             "schedule": "",
             "sys_mod_count": "",
             "ldap_server": "",
             "date_format": "",
             "sys_created_by": "",
             "sys_domain_path": "",
             "city": "",
             "photo": "",
             "employee_number": "",
             "state": "",
             "web_service_access_only": "",
             "phone": "",
             "name": "",
             "mobile_phone": "",
             "sys_tags": "",
             "home_phone": "",
             "sys_created_on": "",
             "gender": "",
             "user_password": "",
             "notification": "",
             "email": "",
             "sys_domain": {
                 "value": "",
                 "link": ""
             },
             "title": "",
             "middle_name": "",
             "last_name": "",
             "sys_updated_on": "",
             "vip": "",
             "last_login_time": "",
             "locked_out": "",
             "location": {
                 "value": "",
                 "link": ""
             },
             "sys_class_name": "",
             "manager": {
                 "value": "",
                 "link": ""
             },
             "time_format": "",
             "active": "",
             "password_needs_reset": "",
             "preferred_language": "",
             "failed_attempts": "",
             "source": "",
             "building": "",
             "user_name": "",
             "street": "",
             "company": {
                 "value": "",
                 "link": ""
             },
             "zip": "",
             "time_zone": "",
             "internal_integration_user": "",
             "sys_id": "",
             "first_name": "",
             "department": {
                 "value": "",
                 "link": ""
             }
         }
     ]
}

operation: Get Assignment Groups

Input parameters

None.

Output

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

The output contains the following populated JSON schema:
{
     "result": [
         {
             "sys_created_on": "",
             "type": "",
             "active": "",
             "sys_updated_by": "",
             "parent": "",
             "source": "",
             "cost_center": "",
             "email": "",
             "manager": "",
             "description": "",
             "roles": "",
             "include_members": "",
             "name": "",
             "default_assignee": "",
             "sys_tags": "",
             "sys_mod_count": "",
             "sys_created_by": "",
             "exclude_manager": "",
             "sys_id": "",
             "sys_updated_on": ""
         }
     ]
}

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.
Active Record Select this option if you want to search only active records in the ServiceNow table.

Output

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

The output contains the following populated JSON schema:
{
     "result": [
         {
             "order": "",
             "made_sla": "",
             "close_notes": "",
             "business_duration": "",
             "opened_at": "",
             "comments": "",
             "closed_by": "",
             "severity": "",
             "description": "",
             "watch_list": "",
             "resolved_by": "",
             "contact_type": "",
             "additional_assignee_list": "",
             "opened_by": {
                 "value": "",
                 "link": ""
             },
             "sys_mod_count": "",
             "number": "",
             "hold_reason": "",
             "correlation_id": "",
             "reopen_count": "",
             "sys_created_on": "",
             "caller_id": {
                 "value": "",
                 "link": ""
             },
             "escalation": "",
             "group_list": "",
             "incident_state": "",
             "sys_updated_by": "",
             "active": "",
             "subcategory": "",
             "state": "",
             "child_incidents": "",
             "work_notes_list": "",
             "follow_up": "",
             "activity_due": "",
             "problem_id": {
                 "value": "",
                 "link": ""
             },
             "sys_tags": "",
             "short_description": "",
             "category": "",
             "upon_reject": "",
             "assignment_group": {
                 "value": "",
                 "link": ""
             },
             "sys_created_by": "",
             "business_stc": "",
             "comments_and_work_notes": "",
             "due_date": "",
             "closed_at": "",
             "assigned_to": {
                 "value": "",
                 "link": ""
             },
             "expected_start": "",
             "work_end": "",
             "correlation_display": "",
             "sys_domain": {
                 "value": "",
                 "link": ""
             },
             "resolved_at": "",
             "approval": "",
             "close_code": "",
             "sys_updated_on": "",
             "rfc": "",
             "parent_incident": "",
             "caused_by": "",
             "upon_approval": "",
             "location": {
                 "value": "",
                 "link": ""
             },
             "sys_class_name": "",
             "user_input": "",
             "time_worked": "",
             "calendar_stc": "",
             "priority": "",
             "approval_history": "",
             "knowledge": "",
             "sys_domain_path": "",
             "notify": "",
             "business_service": "",
             "approval_set": "",
             "work_start": "",
             "sys_id": "",
             "impact": "",
             "parent": "",
             "sla_due": "",
             "company": {
                 "value": "",
                 "link": ""
             },
             "urgency": "",
             "cmdb_ci": {
                 "value": "",
                 "link": ""
             },
             "reassignment_count": "",
             "delivery_task": "",
             "work_notes": "",
             "calendar_duration": "",
             "delivery_plan": ""
         }
     ]
}

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"}
Limit (Optional) Maximum number of results, per page, that this operation should return. By default, this is set as 10000.

Output

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

The output contains the following populated JSON schema:
{
     "result": [
         {
             "order": "",
             "number": "",
             "close_notes": "",
             "business_duration": "",
             "opened_at": "",
             "additional_assignee_list": "",
             "comments": "",
             "closed_by": "",
             "notify": "",
             "description": "",
             "watch_list": "",
             "resolved_by": "",
             "sys_mod_count": "",
             "subcategory": "",
             "sys_domain_path": "",
             "resolved_at": "",
             "parent": "",
             "correlation_id": "",
             "reopen_count": "",
             "sys_created_on": "",
             "caller_id": {
                 "value": "",
                 "link": ""
             },
             "opened_by": {
                 "value": "",
                 "link": ""
             },
             "hold_reason": "",
             "group_list": "",
             "incident_state": "",
             "made_sla": "",
             "active": "",
             "contact_type": "",
             "state": "",
             "child_incidents": "",
             "work_notes_list": "",
             "follow_up": "",
             "activity_due": "",
             "problem_id": {
                 "value": "",
                 "link": ""
             },
             "sys_tags": "",
             "short_description": "",
             "category": "",
             "upon_reject": "",
             "assignment_group": {
                 "value": "",
                 "link": ""
             },
             "sys_created_by": "",
             "business_stc": "",
             "comments_and_work_notes": "",
             "expected_start": "",
             "due_date": "",
             "closed_at": "",
             "calendar_stc": "",
             "time_worked": "",
             "work_end": "",
             "correlation_display": "",
             "sys_domain": {
                 "value": "",
                 "link": ""
             },
             "rfc": "",
             "approval": "",
             "close_code": "",
             "sys_updated_on": "",
             "parent_incident": "",
             "caused_by": "",
             "work_start": "",
             "upon_approval": "",
             "location": {
                 "value": "",
                 "link": ""
             },
             "sys_class_name": "",
             "priority": "",
             "severity": "",
             "assigned_to": {
                 "value": "",
                 "link": ""
             },
             "escalation": "",
             "user_input": "",
             "approval_history": "",
             "knowledge": "",
             "business_service": "",
             "approval_set": "",
             "urgency": "",
             "sys_id": "",
             "impact": "",
             "sys_updated_by": "",
             "sla_due": "",
             "company": {
                 "value": "",
                 "link": ""
             },
             "cmdb_ci": {
                 "value": "",
                 "link": ""
             },
             "reassignment_count": "",
             "delivery_task": "",
             "work_notes": "",
             "calendar_duration": "",
             "delivery_plan": ""
         }
     ]
}

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.

The output contains the following populated JSON schema:
{
     "result": []
}

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.

The output contains the following populated JSON schema:
{
     "result": {
         "order": "",
        nbsp; "number": "",
         "close_notes": "",
         "business_duration": "",
         "opened_at": "",
         "additional_assignee_list": "",
         "comments": "",
         "closed_by": "",
         "notify": "",
         "description": "",
         "watch_list": "",
         "resolved_by": "",
         "sys_mod_count": "",
         "subcategory": "",
         "sys_domain_path": "",
         "resolved_at": "",
         "parent": "",
         "correlation_id": "",
         "reopen_count": "",
         "sys_created_on": "",
         "caller_id": "",
         "opened_by": {
             "value": "",
             "link": ""
         },
         "hold_reason": "",
         "group_list": "",
         "incident_state": "",
         "made_sla": "",
         "active": "",
         "contact_type": "",
         "state": "",
         "child_incidents": "",
         "work_notes_list": "",
         "follow_up": "",
         "activity_due": "",
         "problem_id": "",
         "sys_tags": "",
         "short_description": "",
         "category": "",
         "upon_reject": "",
         "assignment_group": "",
         "sys_created_by": "",
         "business_stc": "",
         "comments_and_work_notes": "",
         "expected_start": "",
         "due_date": "",
         "closed_at": "",
         "calendar_stc": "",
         "time_worked": "",
         "work_end": "",
         "correlation_display": "",
         "sys_domain": {
             "value": "",
             "link": ""
         },
         "rfc": "",
         "approval": "",
         "close_code": "",
         "sys_updated_on": "",
         "parent_incident": "",
         "caused_by": "",
         "work_start": "",
         "upon_approval": "",
         "location": {
             "value": "",
             "link": ""
         },
         "sys_class_name": "",
         "priority": "",
         "severity": "",
         "assigned_to": "",
         "escalation": "",
         "user_input": "",
         "approval_history": "",
         "knowledge": "",
         "business_service": "",
         "approval_set": "",
         "urgency": "",
         "sys_id": "",
         "impact": "",
         "sys_updated_by": "",
         "sla_due": "",
         "company": "",
         "cmdb_ci": "",
         "reassignment_count": "",
         "delivery_task": "",
         "work_notes": "",
         "calendar_duration": "",
         "delivery_plan": ""
     }
}

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.

The output contains the following populated JSON schema:
{
     "result": {
         "cart_id": "",
         "subtotal": "",
         "items": [
             {
                 "localized_recurring_price": "",
                 "recurring_price": "",
                 "quantity": "",
                 "item_name": "",
                 "price": "",
                 "cart_item_id": "",
                 "localized_price": "",
                 "catalog_item_id": "",
                 "recurring_frequency": ""
             }
         ]
     }
}

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.

The output contains a non-dictionary value.

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.

The output contains the following populated JSON schema:
{
     "result": {
         "total_title": "",
         "subtotal_recurring_price": "",
         "show_subtotal_price": "",
         "none": {
             "total_title": "",
             "subtotal_recurring_price": "",
             "show_subtotal_price": "",
             "subtotal_title": "",
             "items": [
                 {
                     "cart_item_id": "",
                     "recurring_price": "",
                     "quantity": "",
                     "item_name": "",
                     "price": "",
                     "localized_recurring_price": "",
                     "variables": {},
                     "localized_price": "",
                     "catalog_item_id": "",
                     "recurring_frequency": "",
                     "delivery_time": ""
                 }
             ],
             "subtotal_recurring_frequency": "",
             "subtotal_price": ""
         },
         "yearly": {
             "total_title": "",
             "subtotal_recurring_price": "",
             "show_subtotal_price": "",
             "subtotal_title": "",
             "items": [
                 {
                     "cart_item_id": "",
                     "recurring_price": "",
                     "quantity": "",
                     "item_name": "",
                     "price": "",
                     "localized_recurring_price": "",
                     "variables": {
                         "Additional software requirements": "",
                         "Adobe Acrobat": "",
                         "Adobe Photoshop": "",
                         "Optional Software": ""
                     },
                     "localized_price": "",
                     "catalog_item_id": "",
                     "recurring_frequency": "",
                     "delivery_time": ""
                 }
             ],
             "subtotal_recurring_frequency": "",
             "subtotal_price": ""
         },
         "monthly": {
             "total_title": "",
             "subtotal_recurring_price": "",
             "show_subtotal_price": "",
             "subtotal_title": "",
             "items": [
                 {
                     "cart_item_id": "",
                     "recurring_price": "",
                     "quantity": "",
                     "item_name": "",
                     "price": "",
                     "localized_recurring_price": "",
                     "variables": {
                         "Monthly data allowance": "",
                         "Contract duration": "",
                         "Storage": "",
                         "Allocated carrier": "",
                         "Color": ""
                     },
                     "localized_price": "",
                     "catalog_item_id": "",
                     "recurring_frequency": "",
                     "delivery_time": ""
                 }
             ],
             "subtotal_recurring_frequency": "",
             "subtotal_price": ""
         },
         "cart_id": "",
         "subtotal_title": "",
         "subtotal_recurring_frequency": "",
         "subtotal_price": ""
     }
}

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.

The output contains a non-dictionary value.

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.

The output contains the following populated JSON schema:
{
     "result": [
         {
             "description": "",
             "full_description": "",
             "count": "",
             "icon": "",
             "title": "",
             "header_icon": "",
             "homepage_image": "",
             "sys_id": "",
             "subcategories": []
         }
     ]
}

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.

The output contains the following populated JSON schema:
{
     "result": {
         "total_title": "",
         "subtotal_recurring_price": "",
         "show_subtotal_price": "",
         "yearly": {
             "total_title": "",
             "subtotal_recurring_price": "",
             "subtotal_title": "",
             "show_subtotal_price": "",
             "items": [
                 {
                     "cart_item_id": "",
                     "recurring_price": "",
                     "quantity": "",
                     "item_name": "",
                     "price": "",
                     "localized_recurring_price": "",
                     "variables": {
                         "Additional software requirements": "",
                         "Adobe Acrobat": "",
                         "Adobe Photoshop": "",
                         "Optional Software": ""
                     },
                     "localized_price": "",
                     "catalog_item_id": "",
                     "recurring_frequency": "",
                     "delivery_time": ""
                 }
             ],
             "subtotal_recurring_frequency": "",
             "subtotal_price": ""
         },
         "cart_id": "",
         "subtotal_title": "",
         "subtotal_recurring_frequency": "",
         "subtotal_price": ""
     }
}

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 output contains a non-dictionary value.

operation: Get Attachments

Input parameters

Parameter Description
Table Sys ID System ID of the table whose associated attachments you want to retrieve from ServiceNow.

Output

The output contains a non-dictionary value.

operation: Download File

Input parameters

Parameter Description
File Sys ID System ID of the file that you want to download from ServiceNow and add to the FortiSOAR™ "Attachments" module.

Output

The output contains a non-dictionary value.

Included playbooks

The Sample-ServiceNow-3.0.0 playbook collection comes bundled with the VirusTotal connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the ServiceNow connector.

Note: The ServiceNow playbooks are compatible with versions 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 the Schedules module, see the Schedules topic in the FortiSOAR™ documentation.

  • 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
  • Download File
  • Get Assignment Groups
  • Get Attachments
  • Get Cart
  • Get Catalog Categories
  • Get Catalogs
  • Get Items
  • Get ServiceNow Open Tickets
  • Get ServiceNow Resolved Tickets
  • Get Users
  • Search
  • > ServiceNow > Create Incident
  • > ServiceNow > Fetch
  • ServiceNow > Ingest
  • >>ServiceNow > Init Macros
  • ServiceNow On Incident Update
  • 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 the 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 checkbox.
      Adding a ServiceNowTicketStatus picklist
    4. Click Save.
  3. Create another picklist named CreateServiceNowTicketas 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.
      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 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.
      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: 3.0.0

FortiSOAR™ Version Tested on: 6.4.0-1555

ServiceNow Version Tested on : 2.1.0

Authored By: Fortinet

Certified: Yes

Release Notes for version 3.0.0

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

Getting the Client ID and Client Secret from ServiceNow

To support OAuth Authentication for ServiceNow, you need to get Client ID and Client Secret from ServiceNow. To get the Client ID and Client Secret, open ServiceNow and search for OAuth in the ServiceNow navigation. Then, in the System OAuth menu, click Application Registry to create an entry for OAuth as displayed in the following image:

After creating the application registry for OAuth you will get the Client ID and the Client Secret.

Data Ingestion support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling incidents from ServiceNow. The Data Ingestion Wizard pulls "events" from ServiceNow and creates "alerts" in FortiSOAR™.

For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation. The following playbooks to support data ingestion:

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-servicenow

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, click the ServiceNow connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

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.
Client ID Auto-generated unique ID of the client application that is requesting the access token.
Note: For the process to get the Client ID and Client Secret, see the Getting the Client ID and Client Secret from ServiceNow section. 
Client Secret Shared secret string that the instance and the OAuth application use to authorize communications between each other.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.

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 version 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, column name and value, and other input parameters 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
Get Attachments Retrieves attachments from a specific table in ServiceNow based on the system ID of the table you have specified. get_attachments
Investigation
Download File Downloads a specific file from ServiceNow and adds it in the FortiSOAR™ "Attachments" module based on the system ID of the file you have specified. download_file
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.

The output contains the following populated JSON schema:
{
     "result": {
         "order": "",
         "made_sla": "",
         "close_notes": "",
         "business_duration": "",
         "opened_at": "",
         "comments": "",
         "closed_by": "",
         "severity": "",
         "description": "",
         "watch_list": "",
         "resolved_by": "",
         "contact_type": "",
         "additional_assignee_list": "",
         "opened_by": {
             "value": "",
             "link": ""
         },
         "sys_mod_count": "",
         "number": "",
         "hold_reason": "",
         "correlation_id": "",
         "reopen_count": "",
         "sys_created_on": "",
         "caller_id": "",
         "escalation": "",
         "group_list": "",
         "incident_state": "",
         "sys_updated_by": "",
         "active": "",
         "subcategory": "",
         "state": "",
         "child_incidents": "",
         "work_notes_list": "",
         "follow_up": "",
         "activity_due": "",
         "problem_id": "",
         "sys_tags": "",
         "short_description": "",
         "category": "",
         "upon_reject": "",
         "assignment_group": "",
         "sys_created_by": "",
         "business_stc": "",
         "comments_and_work_notes": "",
         "due_date": "",
         "closed_at": "",
         "assigned_to": "",
         "expected_start": "",
         "work_end": "",
         "correlation_display": "",
         "sys_domain": {
             "value": "",
             "link": ""
         },
         "resolved_at": "",
         "approval": "",
         "close_code": "",
         "sys_updated_on": "",
         "rfc": "",
         "parent_incident": "",
         "caused_by": "",
         "upon_approval": "",
         "location": "",
         "sys_class_name": "",
         "user_input": "",
         "time_worked": "",
         "calendar_stc": "",
         "priority": "",
         "approval_history": "",
         "knowledge": "",
         "sys_domain_path": "",
         "notify": "",
         "business_service": "",
         "approval_set": "",
         "work_start": "",
         "sys_id": "",
         "impact": "",
         "parent": "",
         "sla_due": "",
         "company": "",
         "urgency": "",
         "cmdb_ci": "",
         "reassignment_count": "",
         "delivery_task": "",
         "work_notes": "",
         "calendar_duration": "",
         "delivery_plan": ""
     }
}

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.

The output contains the following populated JSON schema:
{
     "result": {
         "order": "",
         "made_sla": "",
         "close_notes": "",
         "business_duration": "",
         "opened_at": "",
         "comments": "",
         "closed_by": "",
         "severity": "",
         "description": "",
         "watch_list": "",
         "resolved_by": "",
         "contact_type": "",
         "additional_assignee_list": "",
         "opened_by": {
             "value": "",
             "link": ""
         },
         "sys_mod_count": "",
         "number": "",
         "hold_reason": "",
         "correlation_id": "",
         "reopen_count": "",
         "sys_created_on": "",
         "caller_id": "",
         "escalation": "",
         "group_list": "",
         "incident_state": "",
         "sys_updated_by": "",
         "active": "",
         "subcategory": "",
         "state": "",
         "child_incidents": "",
         "work_notes_list": "",
         "follow_up": "",
         "activity_due": "",
         "problem_id": "",
         "sys_tags": "",
         "short_description": "",
         "category": "",
         "upon_reject": "",
         "assignment_group": {
             "value": "",
             "link": ""
         },
         "sys_created_by": "",
         "business_stc": "",
         "comments_and_work_notes": "",
         "due_date": "",
         "closed_at": "",
         "assigned_to": {
             "value": "",
             "link": ""
         },
         "expected_start": "",
         "work_end": "",
         "correlation_display": "",
         "sys_domain": {
             "value": "",
             "link": ""
         },
         "resolved_at": "",
         "approval": "",
         "close_code": "",
         "sys_updated_on": "",
         "rfc": "",
         "parent_incident": "",
         "caused_by": "",
         "upon_approval": "",
         "location": {
             "value": "",
             "link": ""
         },
         "sys_class_name": "",
         "user_input": "",
         "time_worked": "",
         "calendar_stc": "",
         "priority": "",
         "approval_history": "",
         "knowledge": "",
         "sys_domain_path": "",
         "notify": "",
         "business_service": "",
         "approval_set": "",
         "work_start": "",
         "sys_id": "",
         "impact": "",
         "parent": "",
         "sla_due": "",
         "company": "",
         "urgency": "",
         "cmdb_ci": "",
         "reassignment_count": "",
         "delivery_task": "",
         "work_notes": "",
         "calendar_duration": "",
         "delivery_plan": ""
     }
}

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 detailed information about ServiceNow users retrieved based on the response fields you have specified.

The output contains the following populated JSON schema:
{
     "result": [
         {
             "default_perspective": "",
             "calendar_integration": "",
             "last_login": "",
             "cost_center": {
                 "value": "",
                 "link": ""
             },
             "introduction": "",
             "sys_updated_by": "",
             "roles": "",
             "country": "",
             "schedule": "",
             "sys_mod_count": "",
             "ldap_server": "",
             "date_format": "",
             "sys_created_by": "",
             "sys_domain_path": "",
             "city": "",
             "photo": "",
             "employee_number": "",
             "state": "",
             "web_service_access_only": "",
             "phone": "",
             "name": "",
             "mobile_phone": "",
             "sys_tags": "",
             "home_phone": "",
             "sys_created_on": "",
             "gender": "",
             "user_password": "",
             "notification": "",
             "email": "",
             "sys_domain": {
                 "value": "",
                 "link": ""
             },
             "title": "",
             "middle_name": "",
             "last_name": "",
             "sys_updated_on": "",
             "vip": "",
             "last_login_time": "",
             "locked_out": "",
             "location": {
                 "value": "",
                 "link": ""
             },
             "sys_class_name": "",
             "manager": {
                 "value": "",
                 "link": ""
             },
             "time_format": "",
             "active": "",
             "password_needs_reset": "",
             "preferred_language": "",
             "failed_attempts": "",
             "source": "",
             "building": "",
             "user_name": "",
             "street": "",
             "company": {
                 "value": "",
                 "link": ""
             },
             "zip": "",
             "time_zone": "",
             "internal_integration_user": "",
             "sys_id": "",
             "first_name": "",
             "department": {
                 "value": "",
                 "link": ""
             }
         }
     ]
}

operation: Get Assignment Groups

Input parameters

None.

Output

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

The output contains the following populated JSON schema:
{
     "result": [
         {
             "sys_created_on": "",
             "type": "",
             "active": "",
             "sys_updated_by": "",
             "parent": "",
             "source": "",
             "cost_center": "",
             "email": "",
             "manager": "",
             "description": "",
             "roles": "",
             "include_members": "",
             "name": "",
             "default_assignee": "",
             "sys_tags": "",
             "sys_mod_count": "",
             "sys_created_by": "",
             "exclude_manager": "",
             "sys_id": "",
             "sys_updated_on": ""
         }
     ]
}

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.
Active Record Select this option if you want to search only active records in the ServiceNow table.

Output

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

The output contains the following populated JSON schema:
{
     "result": [
         {
             "order": "",
             "made_sla": "",
             "close_notes": "",
             "business_duration": "",
             "opened_at": "",
             "comments": "",
             "closed_by": "",
             "severity": "",
             "description": "",
             "watch_list": "",
             "resolved_by": "",
             "contact_type": "",
             "additional_assignee_list": "",
             "opened_by": {
                 "value": "",
                 "link": ""
             },
             "sys_mod_count": "",
             "number": "",
             "hold_reason": "",
             "correlation_id": "",
             "reopen_count": "",
             "sys_created_on": "",
             "caller_id": {
                 "value": "",
                 "link": ""
             },
             "escalation": "",
             "group_list": "",
             "incident_state": "",
             "sys_updated_by": "",
             "active": "",
             "subcategory": "",
             "state": "",
             "child_incidents": "",
             "work_notes_list": "",
             "follow_up": "",
             "activity_due": "",
             "problem_id": {
                 "value": "",
                 "link": ""
             },
             "sys_tags": "",
             "short_description": "",
             "category": "",
             "upon_reject": "",
             "assignment_group": {
                 "value": "",
                 "link": ""
             },
             "sys_created_by": "",
             "business_stc": "",
             "comments_and_work_notes": "",
             "due_date": "",
             "closed_at": "",
             "assigned_to": {
                 "value": "",
                 "link": ""
             },
             "expected_start": "",
             "work_end": "",
             "correlation_display": "",
             "sys_domain": {
                 "value": "",
                 "link": ""
             },
             "resolved_at": "",
             "approval": "",
             "close_code": "",
             "sys_updated_on": "",
             "rfc": "",
             "parent_incident": "",
             "caused_by": "",
             "upon_approval": "",
             "location": {
                 "value": "",
                 "link": ""
             },
             "sys_class_name": "",
             "user_input": "",
             "time_worked": "",
             "calendar_stc": "",
             "priority": "",
             "approval_history": "",
             "knowledge": "",
             "sys_domain_path": "",
             "notify": "",
             "business_service": "",
             "approval_set": "",
             "work_start": "",
             "sys_id": "",
             "impact": "",
             "parent": "",
             "sla_due": "",
             "company": {
                 "value": "",
                 "link": ""
             },
             "urgency": "",
             "cmdb_ci": {
                 "value": "",
                 "link": ""
             },
             "reassignment_count": "",
             "delivery_task": "",
             "work_notes": "",
             "calendar_duration": "",
             "delivery_plan": ""
         }
     ]
}

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"}
Limit (Optional) Maximum number of results, per page, that this operation should return. By default, this is set as 10000.

Output

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

The output contains the following populated JSON schema:
{
     "result": [
         {
             "order": "",
             "number": "",
             "close_notes": "",
             "business_duration": "",
             "opened_at": "",
             "additional_assignee_list": "",
             "comments": "",
             "closed_by": "",
             "notify": "",
             "description": "",
             "watch_list": "",
             "resolved_by": "",
             "sys_mod_count": "",
             "subcategory": "",
             "sys_domain_path": "",
             "resolved_at": "",
             "parent": "",
             "correlation_id": "",
             "reopen_count": "",
             "sys_created_on": "",
             "caller_id": {
                 "value": "",
                 "link": ""
             },
             "opened_by": {
                 "value": "",
                 "link": ""
             },
             "hold_reason": "",
             "group_list": "",
             "incident_state": "",
             "made_sla": "",
             "active": "",
             "contact_type": "",
             "state": "",
             "child_incidents": "",
             "work_notes_list": "",
             "follow_up": "",
             "activity_due": "",
             "problem_id": {
                 "value": "",
                 "link": ""
             },
             "sys_tags": "",
             "short_description": "",
             "category": "",
             "upon_reject": "",
             "assignment_group": {
                 "value": "",
                 "link": ""
             },
             "sys_created_by": "",
             "business_stc": "",
             "comments_and_work_notes": "",
             "expected_start": "",
             "due_date": "",
             "closed_at": "",
             "calendar_stc": "",
             "time_worked": "",
             "work_end": "",
             "correlation_display": "",
             "sys_domain": {
                 "value": "",
                 "link": ""
             },
             "rfc": "",
             "approval": "",
             "close_code": "",
             "sys_updated_on": "",
             "parent_incident": "",
             "caused_by": "",
             "work_start": "",
             "upon_approval": "",
             "location": {
                 "value": "",
                 "link": ""
             },
             "sys_class_name": "",
             "priority": "",
             "severity": "",
             "assigned_to": {
                 "value": "",
                 "link": ""
             },
             "escalation": "",
             "user_input": "",
             "approval_history": "",
             "knowledge": "",
             "business_service": "",
             "approval_set": "",
             "urgency": "",
             "sys_id": "",
             "impact": "",
             "sys_updated_by": "",
             "sla_due": "",
             "company": {
                 "value": "",
                 "link": ""
             },
             "cmdb_ci": {
                 "value": "",
                 "link": ""
             },
             "reassignment_count": "",
             "delivery_task": "",
             "work_notes": "",
             "calendar_duration": "",
             "delivery_plan": ""
         }
     ]
}

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.

The output contains the following populated JSON schema:
{
     "result": []
}

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.

The output contains the following populated JSON schema:
{
     "result": {
         "order": "",
        nbsp; "number": "",
         "close_notes": "",
         "business_duration": "",
         "opened_at": "",
         "additional_assignee_list": "",
         "comments": "",
         "closed_by": "",
         "notify": "",
         "description": "",
         "watch_list": "",
         "resolved_by": "",
         "sys_mod_count": "",
         "subcategory": "",
         "sys_domain_path": "",
         "resolved_at": "",
         "parent": "",
         "correlation_id": "",
         "reopen_count": "",
         "sys_created_on": "",
         "caller_id": "",
         "opened_by": {
             "value": "",
             "link": ""
         },
         "hold_reason": "",
         "group_list": "",
         "incident_state": "",
         "made_sla": "",
         "active": "",
         "contact_type": "",
         "state": "",
         "child_incidents": "",
         "work_notes_list": "",
         "follow_up": "",
         "activity_due": "",
         "problem_id": "",
         "sys_tags": "",
         "short_description": "",
         "category": "",
         "upon_reject": "",
         "assignment_group": "",
         "sys_created_by": "",
         "business_stc": "",
         "comments_and_work_notes": "",
         "expected_start": "",
         "due_date": "",
         "closed_at": "",
         "calendar_stc": "",
         "time_worked": "",
         "work_end": "",
         "correlation_display": "",
         "sys_domain": {
             "value": "",
             "link": ""
         },
         "rfc": "",
         "approval": "",
         "close_code": "",
         "sys_updated_on": "",
         "parent_incident": "",
         "caused_by": "",
         "work_start": "",
         "upon_approval": "",
         "location": {
             "value": "",
             "link": ""
         },
         "sys_class_name": "",
         "priority": "",
         "severity": "",
         "assigned_to": "",
         "escalation": "",
         "user_input": "",
         "approval_history": "",
         "knowledge": "",
         "business_service": "",
         "approval_set": "",
         "urgency": "",
         "sys_id": "",
         "impact": "",
         "sys_updated_by": "",
         "sla_due": "",
         "company": "",
         "cmdb_ci": "",
         "reassignment_count": "",
         "delivery_task": "",
         "work_notes": "",
         "calendar_duration": "",
         "delivery_plan": ""
     }
}

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.

The output contains the following populated JSON schema:
{
     "result": {
         "cart_id": "",
         "subtotal": "",
         "items": [
             {
                 "localized_recurring_price": "",
                 "recurring_price": "",
                 "quantity": "",
                 "item_name": "",
                 "price": "",
                 "cart_item_id": "",
                 "localized_price": "",
                 "catalog_item_id": "",
                 "recurring_frequency": ""
             }
         ]
     }
}

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.

The output contains a non-dictionary value.

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.

The output contains the following populated JSON schema:
{
     "result": {
         "total_title": "",
         "subtotal_recurring_price": "",
         "show_subtotal_price": "",
         "none": {
             "total_title": "",
             "subtotal_recurring_price": "",
             "show_subtotal_price": "",
             "subtotal_title": "",
             "items": [
                 {
                     "cart_item_id": "",
                     "recurring_price": "",
                     "quantity": "",
                     "item_name": "",
                     "price": "",
                     "localized_recurring_price": "",
                     "variables": {},
                     "localized_price": "",
                     "catalog_item_id": "",
                     "recurring_frequency": "",
                     "delivery_time": ""
                 }
             ],
             "subtotal_recurring_frequency": "",
             "subtotal_price": ""
         },
         "yearly": {
             "total_title": "",
             "subtotal_recurring_price": "",
             "show_subtotal_price": "",
             "subtotal_title": "",
             "items": [
                 {
                     "cart_item_id": "",
                     "recurring_price": "",
                     "quantity": "",
                     "item_name": "",
                     "price": "",
                     "localized_recurring_price": "",
                     "variables": {
                         "Additional software requirements": "",
                         "Adobe Acrobat": "",
                         "Adobe Photoshop": "",
                         "Optional Software": ""
                     },
                     "localized_price": "",
                     "catalog_item_id": "",
                     "recurring_frequency": "",
                     "delivery_time": ""
                 }
             ],
             "subtotal_recurring_frequency": "",
             "subtotal_price": ""
         },
         "monthly": {
             "total_title": "",
             "subtotal_recurring_price": "",
             "show_subtotal_price": "",
             "subtotal_title": "",
             "items": [
                 {
                     "cart_item_id": "",
                     "recurring_price": "",
                     "quantity": "",
                     "item_name": "",
                     "price": "",
                     "localized_recurring_price": "",
                     "variables": {
                         "Monthly data allowance": "",
                         "Contract duration": "",
                         "Storage": "",
                         "Allocated carrier": "",
                         "Color": ""
                     },
                     "localized_price": "",
                     "catalog_item_id": "",
                     "recurring_frequency": "",
                     "delivery_time": ""
                 }
             ],
             "subtotal_recurring_frequency": "",
             "subtotal_price": ""
         },
         "cart_id": "",
         "subtotal_title": "",
         "subtotal_recurring_frequency": "",
         "subtotal_price": ""
     }
}

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.

The output contains a non-dictionary value.

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.

The output contains the following populated JSON schema:
{
     "result": [
         {
             "description": "",
             "full_description": "",
             "count": "",
             "icon": "",
             "title": "",
             "header_icon": "",
             "homepage_image": "",
             "sys_id": "",
             "subcategories": []
         }
     ]
}

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.

The output contains the following populated JSON schema:
{
     "result": {
         "total_title": "",
         "subtotal_recurring_price": "",
         "show_subtotal_price": "",
         "yearly": {
             "total_title": "",
             "subtotal_recurring_price": "",
             "subtotal_title": "",
             "show_subtotal_price": "",
             "items": [
                 {
                     "cart_item_id": "",
                     "recurring_price": "",
                     "quantity": "",
                     "item_name": "",
                     "price": "",
                     "localized_recurring_price": "",
                     "variables": {
                         "Additional software requirements": "",
                         "Adobe Acrobat": "",
                         "Adobe Photoshop": "",
                         "Optional Software": ""
                     },
                     "localized_price": "",
                     "catalog_item_id": "",
                     "recurring_frequency": "",
                     "delivery_time": ""
                 }
             ],
             "subtotal_recurring_frequency": "",
             "subtotal_price": ""
         },
         "cart_id": "",
         "subtotal_title": "",
         "subtotal_recurring_frequency": "",
         "subtotal_price": ""
     }
}

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 output contains a non-dictionary value.

operation: Get Attachments

Input parameters

Parameter Description
Table Sys ID System ID of the table whose associated attachments you want to retrieve from ServiceNow.

Output

The output contains a non-dictionary value.

operation: Download File

Input parameters

Parameter Description
File Sys ID System ID of the file that you want to download from ServiceNow and add to the FortiSOAR™ "Attachments" module.

Output

The output contains a non-dictionary value.

Included playbooks

The Sample-ServiceNow-3.0.0 playbook collection comes bundled with the VirusTotal connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the ServiceNow connector.

Note: The ServiceNow playbooks are compatible with versions 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 the Schedules module, see the Schedules topic in the FortiSOAR™ documentation.

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 the 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 checkbox.
      Adding a ServiceNowTicketStatus picklist
    4. Click Save.
  3. Create another picklist named CreateServiceNowTicketas 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.
      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 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.
      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.