Fortinet black logo

ServiceNow v3.0.0

Copy Link
Copy Doc ID 9f06b607-ab1b-11ea-8b7d-00505692583a:26

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.

Important: This version of the connector supports OAUTH with ServiceNow as an OAUTH Provider.

You can use FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling incidents from ServiceNow. For more information, see the Data Ingestion Support section.

Version information

Connector Version: 3.0.0

FortiSOAR™ Version Tested on: 6.4.1-2133

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:

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
Authentication Type Specify the authentication type as either Basic or OAuth.
  • If you select Basic as the authentication type, then you must specify the following parameters:
    • 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.
  • If you select OAuth as the authentication type, then you must specify the following parameters:
    • 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.

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, then click the Create an OAuth API endpoint for external clients option.

Now, you are using OAuth Authentication for ServiceNow.

Next, you need to create an application registry for OAuth as shown in the following image:

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

Note: Version 3.0.0 and later of the connector supports OAUTH with ServiceNow as an OAUTH Provider.

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.

  • Add Item to Cart
  • Advanced Search
  • Create Incident
  • Create Table Record
  • Delete Cart Item
  • Download File
  • Get Assignment Groups
  • Get Attachments
  • Get Cart
  • Get Catalog Categories
  • Get Catalogs
  • Get Items
  • Get Users
  • Search Table Record
  • > ServiceNow > Create Incident
  • > ServiceNow > Fetch
  • ServiceNow > Ingest
  • >>ServiceNow > Init Macros
  • ServiceNow On Incident Update
  • Update Cart Item
  • Update ServiceNow Incident
  • Update ServiceNow Table Record

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.

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling incidents from ServiceNow. Currently, "incidents" in ServiceNow are mapped to "incidents" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.

Configure Data Ingestion

You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming ServiceNow "Incidents" to FortiSOAR™ "Incidents".

The Data Ingestion Wizard enables you to configure scheduled pulling of data from ServiceNow into FortiSOAR™. It also lets you pull some sample data from ServiceNow using which you can define the mapping of data between ServiceNow and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users mostly require to only map any custom fields that are added to the ServiceNow incident.

  1. To begin configuring data ingestion, click Configure Data Ingestion on the ServiceNow connector’s "Configurations" page.
    Click Let’s Start by fetching some data, to open the “Fetch Sample Data” screen.

    Sample data is required to create a field mapping between ServiceNow data and FortiSOAR™. The sample data is pulled from connector actions or ingestion playbooks.
  2. On the Fetch Data screen, provide the configurations required to fetch ServiceNow data.
    Users can choose to pull data from ServiceNow specifying the table name and a query using which you want to pull incidents from ServiceNow. You can also specify additional parameters such as the maximum number of incidents to be fetched, and the last X minutes in which the incidents have been updated in ServiceNow. The fetched data is used to create a mapping between the ServiceNow data and FortiSOAR™ incidents.

    Once you have completed specifying the configurations, click Fetch Data.
  3. On the Field Mapping screen, map the fields of a ServiceNow incident to the fields of an incident present in FortiSOAR™.
    To map a field, click the key in the sample data to add the “jinja” value of the field. For example, to map the state parameter of a ServiceNow incident to the status parameter of a FortiSOAR™ alert, click the Status field and then click the state field to populate its keys:

    For more information on field mapping, see the Data Ingestion chapter in the "Connectors Guide" in the FortiSOAR™ product documentation. Once you have completed mapping fields, click Save Mapping & Continue.

  4. Use the Scheduling screen to configure schedule-based ingestion, i.e., specify the polling frequency to ServiceNow, so that the content gets pulled from the ServiceNow integration into FortiSOAR™.
    On the Scheduling screen, from the Do you want to schedule the ingestion? drop-down list, select Yes.
    In the “Configure Schedule Settings” section, specify the Cron expression for the schedule. For example, if you want to pull data from ServiceNow every 5 minutes, click Every X Minute and in the minute box enter */5. This would mean that based on the configuration you have set up, data, i.e., incidents will be pulled from ServiceNow every 5 minutes.

    Once you have completed scheduling, click Save Settings & Continue.

  5. The Summary screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks. Click Done to complete the data ingestion and exit the Data Ingestion Wizard.

Previous
Next

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.

Important: This version of the connector supports OAUTH with ServiceNow as an OAUTH Provider.

You can use FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling incidents from ServiceNow. For more information, see the Data Ingestion Support section.

Version information

Connector Version: 3.0.0

FortiSOAR™ Version Tested on: 6.4.1-2133

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:

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
Authentication Type Specify the authentication type as either Basic or OAuth.
  • If you select Basic as the authentication type, then you must specify the following parameters:
    • 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.
  • If you select OAuth as the authentication type, then you must specify the following parameters:
    • 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.

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, then click the Create an OAuth API endpoint for external clients option.

Now, you are using OAuth Authentication for ServiceNow.

Next, you need to create an application registry for OAuth as shown in the following image:

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

Note: Version 3.0.0 and later of the connector supports OAUTH with ServiceNow as an OAUTH Provider.

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

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling incidents from ServiceNow. Currently, "incidents" in ServiceNow are mapped to "incidents" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.

Configure Data Ingestion

You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming ServiceNow "Incidents" to FortiSOAR™ "Incidents".

The Data Ingestion Wizard enables you to configure scheduled pulling of data from ServiceNow into FortiSOAR™. It also lets you pull some sample data from ServiceNow using which you can define the mapping of data between ServiceNow and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users mostly require to only map any custom fields that are added to the ServiceNow incident.

  1. To begin configuring data ingestion, click Configure Data Ingestion on the ServiceNow connector’s "Configurations" page.
    Click Let’s Start by fetching some data, to open the “Fetch Sample Data” screen.

    Sample data is required to create a field mapping between ServiceNow data and FortiSOAR™. The sample data is pulled from connector actions or ingestion playbooks.
  2. On the Fetch Data screen, provide the configurations required to fetch ServiceNow data.
    Users can choose to pull data from ServiceNow specifying the table name and a query using which you want to pull incidents from ServiceNow. You can also specify additional parameters such as the maximum number of incidents to be fetched, and the last X minutes in which the incidents have been updated in ServiceNow. The fetched data is used to create a mapping between the ServiceNow data and FortiSOAR™ incidents.

    Once you have completed specifying the configurations, click Fetch Data.
  3. On the Field Mapping screen, map the fields of a ServiceNow incident to the fields of an incident present in FortiSOAR™.
    To map a field, click the key in the sample data to add the “jinja” value of the field. For example, to map the state parameter of a ServiceNow incident to the status parameter of a FortiSOAR™ alert, click the Status field and then click the state field to populate its keys:

    For more information on field mapping, see the Data Ingestion chapter in the "Connectors Guide" in the FortiSOAR™ product documentation. Once you have completed mapping fields, click Save Mapping & Continue.

  4. Use the Scheduling screen to configure schedule-based ingestion, i.e., specify the polling frequency to ServiceNow, so that the content gets pulled from the ServiceNow integration into FortiSOAR™.
    On the Scheduling screen, from the Do you want to schedule the ingestion? drop-down list, select Yes.
    In the “Configure Schedule Settings” section, specify the Cron expression for the schedule. For example, if you want to pull data from ServiceNow every 5 minutes, click Every X Minute and in the minute box enter */5. This would mean that based on the configuration you have set up, data, i.e., incidents will be pulled from ServiceNow every 5 minutes.

    Once you have completed scheduling, click Save Settings & Continue.

  5. The Summary screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks. Click Done to complete the data ingestion and exit the Data Ingestion Wizard.

Previous
Next