ServiceNow is an IT service management platform that helps organizations manage digital workflows for enterprise operations. ServiceNow operations such as creating, updating, or closing tickets can be launched from D3 SOAR with this integration.
D3 SOAR is providing REST operations to function with ServiceNow.
Limitation 1: The integration mapping file only allows mapping concrete CITs and relationships to the CITs and relationships in Servicenow. That is, a parent CIT cannot be used to map its children CIs.
Limitation 2: Since this adapter uses the Servicenow Direct Web Services API, which does not support CI coalescing (reconciliation), if some CIs being pushed from UCMDB are already present in the Servicenow CMDB, before the integration with UCMDB is installed, and if those CIs are (a) also in UCMDB; and (b) pushed into Servicenow by the integration, those CIs are duplicated. (This is because UCMDB does not know these CIs are already in the Servicenow CMDB.) After the adapter is installed, UCMDB keeps track of the CIs it pushes to Servicenow, to prevent duplication.
Limitation 3: Servicenow Web Service Import Sets are currently not supported.
Population Integration:
Limitation 1: Data replication in chunks is not supported.
Limitation 2: Only full synchronization is supported (not delta synchronization).
Limitation 3: Integration only works with Jython 2.5.3 and later.
To connect to ServiceNow from D3 SOAR, please follow this part to collect the required information below:
Parameter
Description
Example
Default
Server URL
The server URL of the ServiceNow instance to connect to.
https://dev12345.service-now.com
Authentication Type
The authentication type (Basic Authentication or OAuth2.0 Authorization Code) for the API connection. Note: For the OAuth2.0 Authorization Code authentication type, ensure you have the System OAuth Application Registry configured.
Basic Authentication
Authentication Type: Basic Authentication
User Name
The user name to authenticate the API connection.
Admin
Password
The password to authenticate the API connection.
Yourpassword
Authentication Type: OAuth2.0 Authorization Code
Client ID
The client ID to authenticate the API connection.
554e****e202011036a272ac****72f1
Client Secret
The client secret to authenticate the API connection.
jFUV****yZvyxorR****Bg==
Authorization Code
The authorization code for the OAuth2.0 authentication. Click the "Get Authorization" button on the Connection page to automatically generate an authorization code.
1l2E*******************************MaQ
Callback URL
The callback URL is used for OAuth2.0 with the grant type of authorization code. Add this URL to your app’s Redirect URIs. In your ServiceNow instance’s console, navigate to System OAuth > ApplicationRegistry > "APP Name"> Redirect URL.
The refresh token for authentication with the grant type of authorization code. Click the "Get Refresh Token" button on the Connection page to automatically generate a refresh token.
This parameter is read-only and auto-generated.
Ajf******************************QzIw
Permission Requirement
Each endpoint in the ServiceNow API requires a certain permission scope. If your connection is built with the Basic authentication type, the following scopes are required for each command. Please note that admin permissions are required for all commands if your connection is built with the OAuth 2.0 authentication type. Refer to Set up OAuth for more details.
Commands
Required Permissions (Basic Authentication)
Remarks
Add Ticket Attachment
No permissions required
Close Tickets
incident_manager
Create Record
admin or dependent on the selected table*
Create Request
catalog_admin
Create Requested Item
catalog_admin
Create Security Incident
sn_si.basic
Create Ticket
incident_manager
Creating a ticket requires no specific permissions, but certain parameters, such as the assigned user, may not be added successfully. If you want to create a ticket with only the required parameters filled, then no permissions are required.
Delete Records
admin or dependent on the selected table*
Download Ticket Attachments
No permissions required
Fetch Event
sn_si.read
Fetch Event can run with no additional permissions. However, the returned events will be limited in quantity.
Get Group Details
admin or no permissions required
Get Group Details can run with no additional permissions. However, the returned raw data will be less detailed.
Get Record Details
admin or dependent on the selected table*
Get Requested Items
sn_request_read
Get Requested Items can run with no additional permissions. However, the returned raw data will be less detailed.
Get Request
admin or no permissions required
Get Request can run with no additional permissions. However, the returned raw data will be less detailed.
Get Security Incidents
sn_si.read
Get SysID
admin or no permissions required
Get SysID can run with no additional permissions. However, the returned raw data will be limited in quantity.
Get Table Fields
sn_sec_core.read_dictionary
Get Tickets
rest_api_explorer
Get Tickets can run with no additional permissions. However, the returned raw data will be less detailed.
Get User Details
rest_api_explorer
Get User Details can run with no additional permissions. However, the returned raw data will be less detailed.
Query Group Members
sn_si.basic
Query Records
admin or dependent on the selected table*
Query Requested Items
sn_request_read
Query Requested Items can run with no additional permissions. However, the returned request items will be limited in quantity.
Query Requests
sn_request_read
Query Requests can run with no additional permissions. However, the returned requests will be limited in quantity.
Query Security Incidents
sn_si.read
Query Server Info
rest_api_explorer
Query Tables
sn_incident_write
Update Records
admin or dependent on the selected table*
Update Request Items
sn_request_write
Update Request
sn_request_write
Update Security Incident
sn_si.basic
Update Tickets
incident_manager
Test Connection
No permissions required
*Finding Table Permissions
If you do not have admin privileges, you need to assign specific roles to the tables you want to access. To ensure security, Access Control Lists (ACLs) are mandatory for anyone other than administrators to work with a table. By creating default security rules, full access to the table will be granted to users with the specified role.
Here are the steps to follow:
In ServiceNow, navigate to All > System Definition > Tables and select the desired table.
Go to Controls > Check Create Access Control. The role needed to access the table will be displayed. Finally, add this role to the user account you are using for connection.
* The Close Ticket command will only be effective if the state is indicated to be 7 in the returned raw data. It is important to note that proper permissions are necessary to carry out this action.
Configuring ServiceNow to Work with D3 SOAR
Creating a User
Log in to ServiceNow.
Select All from the top navigation bar. Type System Security into the filter search bar and select Users under Users and Groups. Click New to add a new user.
Enter a User ID and other required fields, then click Submit.
Set the password for the created user. On the Users page, locate select the created user. Click on Set Password and select Generate. Store the generated password in a secure location. Finally click Save Password.
ALERT
Before a created user can build an integration connection in D3 SOAR, they must log in and reset their password. Otherwise, the error message "Test Connection Failed: {"error":{"message":"User Not Authenticated","detail":"Required to provide Auth information"},"status":"failure"}" will be returned.
Under the Roles tab, click Edit to grant roles to the user you created.
Edit the roles as desired, then click Save. Please refer to Permission Requirement for information on required roles.
Creating an Application Registry for OAuth 2.0 Connections
READER NOTE
The following steps are for OAuth 2.0 configurations. The OAuth 2.0 Client ID and Secret will require admin permission. Please refer to Set up OAuth for more details.
Log in to an account with admin permission.
Select All from the top navigation bar. Type System OAuth into the filter search bar and select Users under Application Registry. Click New to add an application registry.
Select Create an OAuth API endpoint for external clients.
Name the new registry and click Submit. You do not need to manually edit the client ID and secret, these fields will be auto generated.
On the Application Registry page, find the registry you created and open it to view more details.
Click the lock button to get your client secret. You can view the secret again by clicking the lock button.
Click on the lock button adjacent to the Redirect URL field to edit it. Copy and paste the D3 callback URL from the connection to the Redirect URL field (see the OAuth2.0 Authorization Code section of Configuring D3 SOAR to work with ServiceNow), then click Update.
Configuring D3 SOAR to work with ServiceNow
Log in to D3 SOAR.
Find the ServiceNow integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type ServiceNow v2 in the search box to find the integration, then click it to select it.
Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to ServiceNow.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add your desired description for the connection.
Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection. Note: There are two methods of authentication for building the connection between D3 SOAR and ServiceNow. Refer to the section corresponding to your use case below.
If you choose the Basic Authentication Authentication Type:
Input the ServiceNow instance URL for the Server URL.
Select Basic Authentication for Authentication Type.
Input your ServiceNow username.
Input your ServiceNow password.
If you choose the OAuth2.0 Authorization Code Authentication Type:
Input the ServiceNow instance URL for the Server URL.
Select OAuth 2.0 Authorization Code for Authentication Type.
Click Get Authorization. You will be directed to ServiceNow to approve the authorization. Make sure your login user is correct, then click Allow. You will be directed to the Authorization Code page. You may close the page and return to D3 SOAR.
Add the Callback URL to your app's Redirect URIs. In your ServiceNow instance's console, navigate to System OAuth > Application Registry > "APP Name" > Redirect URL.
Click Get Refresh Token. The token will be automatically generated.
Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active. To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmarkappear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
Click +Add to create and add the configured connection.
Commands
ServiceNow includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.
Ticket Sys ID is a required parameterto run this command.
You should already have your desired Ticket Sys IDs on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Ticket Sys IDs. The Ticket Sys IDs can be found in the raw data, at the path $.result[*].sys_id.
Ensure that your input Sys ID belongs to a ticket. To do this, select the Incident Type parameter as "Incident". Note that any other format will not work.
It is not recommended to use the Test Command feature with the Add Ticket Attachment command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:
Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.
Input
Input Parameter
Required/Optional
Description
Example
Ticket Sys ID
Required
The Sys ID of the incident ticket to upload the attachment to. Sys IDs can be obtained using the Fetch Event command.
435******************67b
File IDs
Required
The file paths of the file source.
[ "473" ]
File Source
Required
The file source of the file to attach. The options for file sources are:
Incident Attachment File: Manually uploaded file from Incident
Playbook File: Output from another Task
Artifact File: Ingested Artifact in an Event
Playbook File
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Add Ticket Attachment failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Ticket Sys ID Not Found.
Error Sample Data
Add Ticket Attachment failed.
Status Code: 404.
Message: Ticket Sys ID Not Found.
Close Tickets
Closes incident tickets based on incident ticket Sys ID(s).
READER NOTE
The parameter Ticket Sys IDs is required to run this command.
You should already have your desired Ticket Sys IDs on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Ticket Sys IDs. The Ticket Sys IDs can be found in the raw data, at the path $.result[*].sys_id.
Ensure that your input Sys ID belongs to a ticket. To do this, select the Incident Type parameter as "Incident". Note that any other format will not work.
Resolved By is an optional parameter to run this command.
You can enter a user name, user email or user Sys ID in this field.
If you have a user's email or username, you can input it into the Get User Details command to obtain the corresponding Sys ID. The Sys ID can can be found in the returned raw data, at the path $result[*].sys_id.
User names and user emails can be found from the ServiceNow user interface. Search for System Security, then navigate to Users and Groups > Users.
Input
Input Parameter
Required/Optional
Description
Example
Ticket Sys IDs
Required
The Sys ID(s) of the incident ticket(s) to close. Sys IDs can be obtained using the Fetch Event command.
[ "369*******************f90" ]
Resolution Notes
Required
Notes indicating the reason for closing the ticket.
Closed by admin on 511
Resolution Code
Required
The code to categorize the resolution action of the specified ticket(s).
Resolved by caller
Resolved By
Optional
The user resolving the specified ticket(s). You can enter a user name, user email or user Sys ID. User Sys IDs can be obtained using the Get User Details command.
Mic**** Ho****
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Close Tickets failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Ticket Sys IDs Not Found.
Error Sample Data
Close Tickets failed.
Status Code: 404.
Message: Ticket Sys IDs Not Found.
Create Record
Creates a record in a specified table in ServiceNow. You can get available column elements from the Get Table Fields command.
READER NOTE
Table Name and Record Data are required parameters to run this command.
Run the Query Tables command to obtain Table Names. Table Names can be found in the returned raw data, at the path $.result[*].name.
Run the Get Table Fields command to obtain Record Data available fields. Input the desired table name to obtain the table's available fields. See Where can I get available field's system names? from the FAQ section for more information.
Input
Input Parameter
Required/Optional
Description
Example
Table Name
Required
The name of the table to create a record in. Table Name can be obtained using the Query Tables command.
x_******_test_d3_j**_test***
Record Data
Required
The contents of the record data in JSON format. The available fields can be obtained using the Get Table Fields command.
{
"notes": "A new record by Jon***.",
"passwd": "3**4",
"ip_address": "192.168.*.***",
"sys_tags": "",
"host_name": "d3lab_server**"
}
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Create Record failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid Record Data.
Error Sample Data
Create Record failed.
Status Code: 400.
Message: Invalid Record Data.
Create Request
Creates a new request in the sc_request table.
READER NOTE
Input parameter Custom Fields is optional to run this command
Run the Get Table Fields command to obtain Custom Fields available fields. See Where can I get available field's system names? from the FAQ section for more information on finding the available field names.
Input
Input Parameter
Required/Optional
Description
Example
Short Description
Required
A short description for the new request.
New Request for project D. 512a
Requested For
Optional
The name, email, or Sys ID of the user who raised the request. If this parameter is not defined, requests will be created for the current login user.
Jon***** Wal****
Comments
Optional
The comments for the new request. Comments are visible to all users, fulfillers and requesters.
test comments510
Work Notes
Optional
The work notes for the new request. Work notes are only visible to request fulfillers, and are not shared with requesters.
For VIP
Due Date
Optional
The due date of the new request in UTC time.
2022-06-30 00:00
Custom Fields
Optional
The additional fields in JSON format to input into the request.
{
"assigned_to": "Mic**** Ho****",
"request_state": "requested",
"stage": "requested",
"escalation": "Normal",
"upon_approval": "Proceed to Next Task"
}
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Create Request failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid Custom Fields.
Error Sample Data
Create Request failed.
Status Code: 400.
Message: Invalid Custom Fields.
Create Requested Item
Creates a new Requested Item in the sc_req_item table.
READER NOTE
Request Sys ID Or Number and Custom Fields are optional parameters to run this command.
Run the Get Request command to obtain Request Sys IDs and Numbers. Request Sys IDs can be found in the returned raw data, at the path $.result[*].sys_id; Request Numbers can be found in the returned raw data, at the path $.result[*].number.
Run the Get Table Fields command to obtain Custom Fields available fields. See Where can I get available field's system names? from the FAQ section for more information on finding the available field names.
Input
Input Parameter
Required/Optional
Description
Example
Short Description
Required
A short description of the new requested item.
Apple iPhone13 0512a
Comments
Optional
The comments for the new requested item. Comments are visible to all users, fulfillers and requesters.
New req item iphone13
Work Notes
Optional
The work notes for the new requested item. Work notes are only visible to request fulfillers, and are not shared with requesters.
Sensitive info inside
Due Date
Optional
The due date of the new requested item in UTC time.
2022-06-30 00:00
Request Sys ID Or Number
Optional
The Sys ID or request number of the requested item(s). Request Sys ID and request numbers can be obtained using the Get Request command.
REQ*******
Custom Fields
Optional
The additional fields in JSON format to input into the requested item.
{
"urgency": "2"
}
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Create Request Item failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Request ID Not Found.
Error Sample Data
Create Request Item failed.
Status Code: 404.
Message: Request ID Not Found.
Create Security Incident
Creates a security incident based on specified information, and optionally uploads attachment(s) to the security incident.
READER NOTE
Requested By, Assignment Group, Assigned User and Custom Fields are optional parameters to run this command.
If you have a user's email or username, you can input it into the Get User Details command to obtain the corresponding Sys IDs. The input Sys IDs for the Requested By and Assigned User parameters can can be found in the returned raw data, at the path $result[*].sys_id.
User names and user emails can be found from the ServiceNow user interface. Search for System Security, then navigate to Users and Groups > Users.
Run the Get Group Details command to obtain Assignment Groups. Group Names can be found in the returned raw data, at the path $.result[*].name, Group Sys IDs can be found in the raw data, at the path $.result[*].sys_id.
Run the Get Table Fields command to obtain Custom Fields available fields. See Where can I get available field's system names? from the FAQ section for more information on finding the available field names
ALERT
Due to recent changes in the ServiceNow API, there are some limitations when using the Assignment Group and Assigned To parameters. The following restrictions apply when using these parameters:
You can only use this command to assign users to security incidents in the Security Incident Assignment group:
The user must be part of the Security Incident Assignment group. This can be checked and modified from the ServiceNow user interface.
Both the assignment group and assigned to parameters must be defined in the command.
If you wish to assign an incident to a group other than the Security Incident Assignment group, you should follow these steps:
Enter the desired group name in the Assignment Group parameter, and leave the Assigned User parameter empty.
Run the Update Security Incident command to assign the incident to the desired user.
It is not recommended to use the Test Command feature with the Create Security Incident command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:
Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.
Input
Input Parameter
Required/Optional
Description
Example
Short Description
Required
A short description for the new security incident.
Sec Incident 0511a
Requested By
Optional
The user name, email, or Sys ID of the requesting user. User names, emails and Sys IDs can be obtained using the Get User Details command. If this parameter is not defined, the requests will be created for the current login user. Note: The admin user cannot be the requester unless the login user account is an admin user.
Ja** Erl******
Business Impact
Optional
The impact level of the security incident. If this field is not defined, the default impact level will be set to Low.
High
Priority
Optional
The priority level of the security incident. If this field is not defined, the default priority level will be set to Low.
Moderate
Category
Optional
The category of the security incident. If this field is not defined, the default category will be set to None.
Unpatched Vulnerability
Assignment Group
Optional
The name or Sys ID of the group to assign the security incident to. Group names and Sys IDs can be obtained using the Get Group Details command.
Problem Analyzers
Assigned User
Optional
The user name, email or Sys ID of the user assigned to the security incident. User names, emails and Sys IDs can be obtained using the Get User Details command.
Note: If you input values for both the Assignment Group and Assigned User parameters, ensure that the user is in the group. Otherwise, the error message "Operation Failed" will be returned. You can use the Query Group Members command to check if the user is in the group.
Jon***** Wal****
Description
Optional
A description for the new security incident.
Test description 0511c
Custom Fields
Optional
The additional fields in JSON format to input into the security incident.
{
"comments": "510c These are my comments",
"subcategory": "37"
}
File IDs
Optional
The file paths of the file source.
[
"749"
]
File Source
Optional
The file source of the file to attach. The options for file sources are:
Incident Attachment File: Manually uploaded file from Incident
Playbook File: Output from another Task
Artifact File: Ingested Artifact in an Event
Playbook File
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Create Security Incident failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: User Not Exist.
Error Sample Data
Create Security Incident failed.
Status Code: 404.
Message: User Not Exist.
Create Ticket
Creates an incident ticket and optionally upload attachment(s) to the ticket.
READER NOTE
Caller ID, Assignment Group, Assigned User and Custom Fields are optional parameters to run this command.
If you have a user's email or username, you can input it into the Get User Details command to obtain the corresponding Sys IDs. The input Sys IDs for the Caller ID and Assigned User parameters can can be found in the returned raw data, at the path $result[*].sys_id.
User names and user emails can be found from the ServiceNow user interface. Search for System Security, then navigate to Users and Groups > Users.
Run the Get Group Details command to obtain Assignment Groups. Group Names can be found in the returned raw data, at the path $.result[*].name, Group Sys IDs can be found in the raw data, at the path $.result[*].sys_id.
Run the Get Table Fields command to obtain Custom Fields available fields. See Where can I get available field's system names? from the FAQ section for more information on finding the available field names.
ALERT
You will need to make sure the Assigned User is in the Assignment Group you entered if you choose to enter values for both the Assignment Group and Assigned User fields. Otherwise, D3 SOAR will return the error of “Operation Failed” error message.
It is recommended to run the Query Group Members command to check whether the user is in the group, if you choose to input values for both fields.
It is not recommended to use the Test Command feature with the Create Ticket command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:
Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.
Input
Input Parameter
Required/Optional
Description
Example
Short Description
Required
A short description for the new incident ticket.
Test incident creation through REST 0510c
Caller ID
Optional
The user name, user email, or user Sys ID of the caller. User names, user email or user Sys IDs can be obtained using the Get User Details command. If this field is not specified, the caller will be the current login user. Note: The admin user cannot be the caller unless the login user account is an admin user.
Ja** Erl******
Impact
Optional
The impact level of the incident ticket. The default impact level is Low.
Low
Urgency
Optional
The urgency level of the incident. The default urgency level is Low.
Low
Category
Optional
The category of the incident ticket. The default category is Inquiry/Help.
Inquiry/Help
Assignment Group
Optional
The name or Sys ID of the group to assign the incident ticket to. Group names and Sys IDs can be obtained using the Get Group Details command.
Problem Analyzers
Assigned User
Optional
The user name, email or Sys ID of the user assigned to the incident ticket. User names, emails and Sys IDs can be obtained using the Get User Details command.
Note: If you input values for both the Assignment Group and Assigned User parameters, ensure that the user is in the group. Otherwise, the error message "Operation Failed" will be returned. You can use the Query Group Members command to check if the user is in the group.
Jon***** Wal****
Description
Optional
A description for the incident ticket.
Test description 0510c
Custom Fields
Optional
The additional fields in JSON format to input into the incident ticket.
{
"comments": "comment0510c",
"subcategory": "DNS"
}
File IDs
Optional
The file paths of the file source.
[
"278"
]
File Source
Optional
The file source of the file to attach. The options for file sources are:
Incident Attachment File: Manually uploaded file from Incident
Playbook File: Output from another Task
Artifact File: Ingested Artifact in an Event
Playbook File
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Create Ticket failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid Custom Fields.
Error Sample Data
Create Ticket failed.
Status Code: 400.
Message: Invalid Custom Fields.
Delete Records
Deletes the specified records from a specified table in ServiceNow.
READER NOTE
Table Name and Record Sys IDs are required parameters to run this command.
Run the Query Tables command to obtain Table Names. Table Names can be found in the returned raw data, at the path $.result[*].name.
Run the Query Records command to obtain Record Sys IDs. Record Sys IDs can be found in the returned raw data, at the path $.result.[*].sys_id.
ALERT
You will need to make sure the Table Name matches the Record Sys IDs. Otherwise, D3 SOAR will return an error.
It is recommended to run the Query Tables command first and choose the table name you want to get the record from. Use that table name as the input value to run the Query Records command to get Record Sys IDs.
When inputting Table Names and Record Sys IDs you get from running other commands ensure these pairs of values match.
Input
Input Parameter
Required/Optional
Description
Example
Table Name
Required
The name of the table to delete records from. Table names can be obtained using the Query Tables command.
x_******_test_d3_j**_test***
Record Sys IDs
Required
The Sys IDs of the records to delete. Record Sys IDs can be obtained using the Query Records command.
[ "366********************697"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Raw Data
The primary response data from the API request.
The original ServiceNow API response is empty, D3 added custom fields id and actionResult to help the user get which record has been deleted and whether the deletion is successful.
SAMPLE DATA
CODE
[
{
"id": ["366********************697"],
"actionResult": ["Delete the record successfully"]
}
]
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
id
actionResult
366********************697
Delete the record successfully
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Delete Records failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Record Not Found.
Error Sample Data
Delete Records failed.
Status Code: 404.
Message: Record Not Found.
Download Ticket Attachments
Downloads attachments of the specified incident ticket.
READER NOTE
Ticket Sys ID is a required parameter to run this command.
You should already have your desired Ticket Sys IDs on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Ticket Sys IDs. The Ticket Sys IDs can be found in the raw data, at the path $.result[*].sys_id.
If no files exist in the specified ticket, the command will run successfully with no returned results. Please verify your input Ticket Sys ID.
Ensure that your input Sys ID belongs to a ticket. To do this, select the Incident Type parameter as "Incident". Note that any other format will not work.
Input
Input Parameter
Required/Optional
Description
Example
Ticket Sys ID
Required
The Sys ID of the incident ticket to download attachment(s) from. Sys IDs can be obtained using the Fetch Event command.
ae9*********************0ac
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Raw Data
The primary response data from the API request.
The original ServiceNow API response does not contain enough information. D3 customizes the raw data by adding “fileId”, “fileName”, “md5”, “sha1” and “sha256” fields to provide more download details.
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
fileId
fileName
md5
sha1
sha256
305
invoice (2).pdf
8F8*********************62F
E5D***********************F39
52D******************************************282
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Download Ticket Attachments failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Ticket Not Found.
Error Sample Data
Download Ticket Attachments failed.
Status Code: 404.
Message: Ticket Not Found.
Fetch Event
Returns incident ticket(s) or Security Incident(s) as Event(s) from the ServiceNow platform based on specified criteria.
Input
Input Parameter
Required/Optional
Description
Example
Start Time
Optional
The start time of the time range to fetch incident tickets/Security Incidents by the specified query time field (created time or updated time), in UTC time.
2022-04-01 00:00
End Time
Optional
The end time of the time range to fetch incident tickets/Security Incidents by the specified query time field (created time or updated time), in UTC time. If not specified, the current time will be the end time.
2022-04-20 00:00
Number of Event(s) Fetched
Optional
The maximum number of the most recent incident tickets to fetch. The default value is 100. Note: If the input limit value is too large, it may affect system performance when returning a large volume of results.
Note: If the query field does not exist in the table, all records will be returned. Fields and operators are case-sensitive. Do not leave a space between an operator and a value. For example, for the search condition numberLIKE10004, LIKE is the operator, and 10004 is the value. There should be no space between LIKE and 10004.
severity=3^active=true
Tolerance Scope
Optional
The tolerance scope in minutes of the query to get incident tickets between start and end time to avoid the loss of tickets. The incident tickets will be fetched between {Start Time - Tolerance Scope, End Time}
10
Incident Type
Optional
The incident type of the events to fetch. The available options are Incident and Security Incident. If this parameter is not defined, the default value is Incident.
Security Incident
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.
If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.
As a system integration, the Servicenow integration has some pre-configured field mappings for default field mapping.
Default Event Source
The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. The default event source has a “Main Event JSON Path” (i.e., $.results) that is used to extract a batch of events from the response raw data. Click Edit Main JSON Path to view the “Main Event JSON Path”.
Main Event JSON Path: $.result The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.
For example, the root node of a JSON Path is result. The child node denoting the Unique Event Key field would be sys_id. Putting it together, the JSON Path expression to extract the Unique Event Key is $.value.sys_id.
The pre-configured field mappings are detailed below:
Field Name
Source Field
Unique Event Key
.sys_id
Start Time
.sys_created_on
Description
.description
IncidentNumber
.number
Event Type
.category
Priority
.priority
Severity
.severity
Urgency
.urgency
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Fetch Event failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: The value for parameter (Top Recent Event Number) is invalid.
Error Sample Data
Fetch Event failed.
Status Code: 400.
Message: The value for parameter (Top Recent Event Number) is invalid.
Get Group Details
Retrieves group details by whole or partial group name.
READER NOTE
If you have an invalid input for the Group Names parameter, D3 SOAR will only return results from valid inputs and ignore invalid ones.
Partial group name means only partial character inputs can be used for search. For example, if your input is “pro”, all groups with names containing such as “Problem”, “Project”, “Approves” will all be returned.
Input
Input Parameter
Required/Optional
Description
Example
Group Names
Optional
The whole or partial name of the group to retrieve details. If this parameter is not defined, the command will return a maximum of 10,000 with all corresponding details.
[
"Problem Analyzers",
"admin"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
Groups Count
1000
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Group Details failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid Group Names.
Error Sample Data
Get Group Details failed.
Status Code: 400.
Message: Invalid Group Names.
Get Record Details
Retrieves the details of the specified records in ServiceNow.
READER NOTE
Table Name and Record Sys IDs are required parameters to run this command.
Run the Query Tables command to obtain Table Names. Table Names can be found in the returned raw data, at the path $.result[*].name.
Run the Query Records command to obtain Record Sys IDs. Record Sys IDs can be found in the raw data, at the path $.result[*].sys_id.
ALERT
You will need to make sure the Table Name matches the Record Sys IDs. Otherwise, D3 SOAR will return an error.
It is recommended to run the Query Tables command first and choose the table name you want to get the record from. Use that table name as the input value to run the Query Records command to get Record Sys IDs.
When inputting Table Names and Record Sys IDs you get from running other commands ensure these pairs of values match.
Input
Input Parameter
Required/Optional
Description
Example
Table Name
Required
The name of the table to retrieve record details. Table names can be obtained using the Query Tables command.
x_******_test_d3_j**_test***
Record Sys IDs
Required
The Sys IDs of the records to retrieve details. Record Sys IDs can be obtained using the Query Records command.
[
"vrcR******************Mfd"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Record Details failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Record Not FoundI.
Error Sample Data
Get Record Details failed.
Status Code: 404.
Message: Record Not Found.
Get Requested Items
Retrieves specified requested items.
READER NOTE
The parameter Request Item Sys IDs Or Numbers is optional to run this command.
Run the Query Request Items command to obtain Request Item Sys IDs or Numbers. Request Item Sys IDs can be found in the raw data, at the path $.result[*].sys_id; Request Item Numbers can be found in the raw data, at the path $.result[*].number.
Input
Input Parameter
Required/Optional
Description
Example
Request Item Sys IDs Or Numbers
Optional
The Sys ID or number of the requested items to retrieve details. Item Sys IDs and numbers can be obtained using the Query Request Items command.
[
"056********************05d",
"RITM00*****"
]
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
Request Items Count
1000
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Request Items failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Name Not Found.
Error Sample Data
Get Request Items failed.
Status Code: 404.
Message: Name Not Found.
Get Request
Retrieves specified requests.
READER NOTE
The parameter Request Sys IDs Or Numbers is optional to run this command.
Run the Query Request Items command to obtain Request Item Sys IDs Or Numbers. Request Sys IDs can be found in the raw data, at the path $.result[*].sys_id; Request Numbers can be found in the raw data, at the path $.result[*].number.
Input
Input Parameter
Required/Optional
Description
Example
Request Sys IDs Or Numbers
Optional
The Sys ID or number of the requests to retrieve details. Request Sys IDs and numbers can be obtained using the Query Requests command. If this parameter is not defined, all requests will be returned.
[
"ca7**********************08a",
"REQ00*****"
]
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
Requests Count
1000
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Request failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Name Not Found.
Error Sample Data
Get Request failed.
Status Code: 404.
Message Name Not Found.
Get Security Incidents
Retrieves security incidents based on Security Incident numbers or Security Incident Sys ID(s).
READER NOTE
Input parameter Security Incident Sys IDs Or Numbers is optional to run this command.
Run the Query Security Incidents command to obtain Request Item Sys IDs and Numbers. Sys IDs can be found in the raw data, at the path $.result[*].sys_id; Numbers can be found in the raw data, at the path $.result[*].number. Alternatively, you can run the Fetch Event command with the Incident Type parameter set to Incident to obtain the values.
Input
Input Parameter
Required/Optional
Description
Example
Security Incident Sys IDs Or Numbers
Optional
The SYS IDs or numbers of the security incidents to retrieve details. Sys IDs and numbers can be obtained using the Query Security Incidents command.
[
"eb7*****************091",
"SIR00*****"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
Security Incidents Count
1000
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Security Incident failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Numbers Not Found.
Error Sample Data
Get Security Incident failed.
Status Code: 404.
Message: Numbers Not Found.
Get Sys ID
Retrieves Sys ID based on the number of the Ticket, security Incident, Request or Requested item.
READER NOTE
Number and Table Name are required parameters to run this command.
The Number must matchthe Table Name. Otherwise, nothing will be returned.
If the input Table Name is Ticket, you willneed a Ticket Number to run this command. If you need a Ticket Number, run the Fetch Event command with the Incident Type parameter set to Incident. The Ticket Number can be in the returned raw data, at the path $.result[*].number. The format is in the form of "INC…".
If the input Table Name is Security Incident, you will need a Security Incident Number to run this command. If you need a Security Incident Number, run the Query Security Incidents or Fetch Event command. For the Query Security Incidents command, the Security Incidents Number can be found from the returned raw data, at the path the $.result[*].number. The format is in the form of "SIR…". For the Fetch Event command, run the command with the Incident Type parameter set to Security Incident. The Security Incident Number can be found in the returned raw data, at the path $.result[*].number. The format is in the form of "SIR…".
If the input Table Name is Request, you will need a Request Number to run this command. If you need a Request Number, run the Query Requests command. The Request Number can be found from the returned raw data, at the path $.result[*].number. The format is in the form of "REQ…".
If the input Table Name is Request Item, you will need a Request Item Number to run this command. If you need a Request Item Number, run the Query Requested Items command. The Request Item Number can be found in the returned raw data, at the path $.result[*].number. The format is in the form "RITM…".
Inputs that are invalid or do not match will result in a successful response with no output data.
Input
Input Parameter
Required/Optional
Description
Example
Number (Ticket, Security Incident, Request, Request Item)
Required
The number of the specified Incident Ticket, Security Incident, Request or Request_Item. Numbers can be obtained from the ServiceNow user interface. Incident Ticket numbers start with INC. SecurityIncident numbers start with SIR. Request numbers start with REQ. Request_Item numbers start with RITM.
SIR00*****
Table Name
Required
The name of the table to retrieve the Sys ID from.
Security Incident
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Sys ID failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 403.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: User Not Authenticated.
Error Sample Data
Get Sys ID failed.
Status Code: 403.
Message: User Not Authenticated.
Get Table Fields
Lists all fields of the specified table.
READER NOTE
Table Name is a required parameter to run this command.
Run the Query Tables command to obtain Table Name. Table Names can be found in the returned raw data, at the path $.result[*].name.
Input
Input Parameter
Required/Optional
Description
Example
Table Name
Required
The name of the table to list all field information. Table names can be obtained using the Query Tables command.
sn_si_incident
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Table Fields failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 403.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: User Not Authenticated.
Error Sample Data
Get Table Fields failed.
Status Code: 403.
Message: User Not Authenticated.
Get Tickets
Retrieves the specified incident ticket details.
READER NOTE
The parameter Ticket Sys IDs Or Numbers is required to run this command.
You should already have your desired Ticket Sys IDs or Numbers on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Ticket Sys IDs or Numbers. The Ticket Sys IDs can be found in the raw data at the path $.result[*].sys_id; Numbers can be found in the the raw data at the path $.result[*].number.
Ensure that your input Sys ID belongs to a ticket. To do this, select the Incident Type parameter as "Incident". Note that any other format will not work.
Input
Input Parameter
Required/Optional
Description
Example
Ticket Sys IDs Or Numbers
Required
The Sys ID or number of the incident tickets to retrieve details. Ticket Sys IDs and numbers can be obtained using the Fetch Event command. Note: Incident Ticket numbers start with “INC”.
[
"b71************************087",
"INC000****"
]
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Tickets failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 403.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: User Not Authenticated.
Error Sample Data
Get Tickets failed.
Status Code: 403.
Message: User Not Authenticated.
Get User Details
Retrieves user details by username or email address.
READER NOTE
The parameter User Names or Emails is required to run this command.
User Names and Emails can be found on the ServiceNow user interface. In ServiceNow, search for System Security, then navigate to Users and Groups > Users.
Input
Input Parameter
Required/Optional
Description
Example
User Names or Emails
Required
The username or email of the users to retrieve user details. Note: Both whole and partial usernames are acceptable for input.
[
"jona****",
"mi*****"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get User Details failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the Service HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: User Name Not Found.
Error Sample Data
Get User Details failed.
Status Code: 404.
Message: User Name Not Found.
Query Group Members
Retrieves member information of the specific group(s) based on query conditions.
READER NOTE
Group Name and Query are optional parameters to run this command.
Run the Get Group Details command to obtain Group Names. Group Names can be found in the returned raw data at the path $.result[*].name.
If you need to find a user Sys_ID for the Query parameter, run the Get User Details command.
A partial group name allows for search results to be generated using only a portion of the group name. For example, if the search term is "pro", all groups with names containing "pro" (such as "Problem", "Project", or "Approves") will be returned.
Input
Input Parameter
Required/Optional
Description
Example
Group Name
Optional
The whole or partial name of the group to retrieve member details. If this field is not defined, the command will return users from all groups. Group Name can be obtained using the Get Group Details command.
Note: Avoid placing a space between an operator and its value. For example, instead of "user LIKE jona****", use "user LIKEjona****". Use operator "LIKE" with user names, and use operator "=" with user Sys_IDs. User Sys_IDs can be obtained using the Get User Details command.
user =ea8****************ddb
Limit
Optional
The maximum number of group members to return. The default value is 100. Note: If the input limit value is too large, it may affect system performance when returning a large volume of results. Set a suitable limit value to prevent this issue from occurring.
5
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Create Request failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 403.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: You must have a valid Support account to call this API.
Error Sample Data
Create Request failed.
Status Code: 403.
Message: You must have a valid Support account to call this API.
Query Records
Retrieves the records with a specified query from the table in ServiceNow.
READER NOTE
Table Name is a required parameter to run this command.
Run the Query Tables command to obtain Table Name. Table Names can be found in the returned raw data, at the path $.result[*].name.
Input
Input Parameter
Required/Optional
Description
Example
Table Name
Required
The name of the table to query records. Table names can be obtained using the QueryTables command.
x_******_test_d3_j**_test***
Query
Required
The query to retrieve records. For more information about the query syntax, see Operators available for filters and queries. If the input query field does not exist in the specified table, all records will be returned.
Note: Fields and operators are case-sensitive. Avoid placing a space between an operator and its value. For example, instead of "number LIKE 10004", use "numberLIKE10004" (LIKE is the operator, 10004 is the value).
name=mi*****^numberLIKE10004
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Query Records Failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Table Name Not Found.
Error Sample Data
Query Records Failed.
Status Code: 404.
Message: Table Name Not Found.
Query Requested Items
Retrieves Requested Item(s) from the Requested Item table based on the query condition.
Input
Input Parameter
Required/Optional
Description
Example
Query
Optional
The query to retrieve requested items. For more information about the query syntax, see Operators available for filters and queries. If the input query field does not exist in the specified table, all records will be returned.
Note: Fields and operators are case-sensitive. Avoid placing a space between an operator and its value. For example, instead of "number LIKE 10004", use "numberLIKE10004" (LIKE is the operator, 10004 is the value).
numberLIKERITM00***** ^priority<=4
Limit
Optional
The maximum number of requested items to return. The default value is 100. Note: If the input limit value is too large, it may affect system performance when returning a large volume of results. Set a suitable limit value to prevent this issue from occurring.
5
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Query Request Items failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid Query.
Error Sample Data
Query Request Items failed.
Status Code: 400.
Message: Invalid Query.
Query Requests
Retrieves request(s) from the sc_request table based on the query condition.
Input
Input Parameter
Required/Optional
Description
Example
Query
Optional
The query to filter results. For more information about the query syntax, see Operators available for filters and queries. If the input query field does not exist in the specified table, all records will be returned.
Note: Avoid placing a space between an operator and its value. For example, instead of "number LIKE REQ001000", use "numberLIKEREQ001000" (LIKE is the operator, REQ001000 is the value).
numberLIKEREQ00100^priority<=3
Limit
Optional
The maximum number of requests to return. The default value is 100. Note: If the input limit value is too large, it may affect system performance when returning a large volume of results. Set a suitable limit value to prevent this issue from occurring.
5
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Create Requests failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid Query.
Error Sample Data
Create Requests failed.
Status Code: 400.
Message: Invalid Query.
Query Security Incidents
Retrieves security incidents based on the query condition.
Note: Avoid placing a space between an operator and its value. For example, instead of "number LIKE SIR00*****", use "numberLIKESIR00*****" (LIKE is the operator, SIR00***** is the value).
priority <=2 ^ numberLIKESIR00100
Limit
Optional
The maximum number of security incidents to return. The default value is 100. Note: If the input limit value is too large, it may affect system performance when returning a large volume of results. Set a suitable limit value to prevent this issue from occurring.
3
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Query Security Incidents failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid Query.
Error Sample Data
Query Security Incidents failed.
Status Code: 400.
Message: Invalid Query.
Query Server Info
Queries server info by server IP address or server name.
READER NOTE
The parameter Server Names or IPs is required to run this command.
You should already have your desired Server Names or IPs on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Server Names or IPs. They will be listed if the records have related information.
Input
Input Parameter
Required/Optional
Description
Example
Server Names or IPs
Required
The server ID’s IP addresses or server names to query. Server Names or IPs can be obtained using the Fetch Event command.
[
"192.168.***.***",
"je**c"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Query Server Info failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Server Name Not Found.
Error Sample Data
Query Server Info failed.
Status Code: 404.
Message: Server Name Not Found.
Query Tables
Retrieves table information based on the query conditions.
Note: Avoid placing a space between an operator and its value. For example, instead of "sys_created_by = system", use "sys_created_by=system" (= is the operator, system is the value). When an invalid field name is specified in a query, the instance will only use the valid part of the query and return the corresponding rows. The behavior of returning no rows on an invalid query can be controlled by setting the property "glide.invalid_query.returns_no_rows" to true using the Update Records command on the "sys_properties" table.
sys_created_by=system^labelLIKEApplication Model
Limit
Optional
The maximum number of tables to return. The default value is 100. Note: If the input limit value is too large, it may affect system performance when returning a large volume of results. Set a suitable limit value to prevent this issue from occurring.
5
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Query Tables failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 403.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid Query.
Error Sample Data
Query Tables failed.
Status Code: 403.
Message: Invalid Query.
Update Records
Updates the records in a specified table in ServiceNow.
READER NOTE
Table Name, Record Sys IDs and Record Data are required parameters to run this command.
Run the Query Tables command to obtain Table Name. Table Names can be found in the returned raw data, at the path $.result[*].name.
Run the Query Records command to obtain Record Sys IDs. Query Records can be found in the returned raw data, at the path $.result[*].sys_id.
Run the Get Table Fields command to obtain Record Data available fields. Input the desired table name to obtain the table's available fields. See Where can I get available field's system names? from the FAQ section for more information.
It is recommended to make a copy of your original record data and make changes to the desired fields, as the new record data will replace the old one.
ALERT
You will need to make sure the Table Name matches the Record Sys IDs. Otherwise, D3 SOAR will return an error.
It is recommended to run the Query Tables command first and choose the table name you want to get the record from. Use that table name as the input value to run the Query Records command to get Record Sys IDs.
When inputting Table Names and Record Sys IDs you get from running other commands ensure these pairs of values match.
Input
Input Parameter
Required/Optional
Description
Example
Table Name
Required
The name of the table to update records. Table names can be obtained using the Query Tables command.
x_******_test_d3_j**_test***
Record Sys IDs
Required
The Sys IDs of the records to update. Record Sys IDs can be obtained using the Query Records command.
[
"366********************697"
]
Record Data
Required
The updated JSON-formatted record data.
{
"notes": "A test work note by Jone***."
}
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Update Records failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Table Not Found.
Error Sample Data
Update Records failed.
Status Code: 404.
Message: Table Not Found.
Update Requested Items
Updates field information of the specified Requested Item(s).
READER NOTE
The parameter Request Item Sys IDs is required to run this command.
Run the Query Requested Items command to obtain Request Item Sys IDs. The Request Item Sys IDs can be found in the returned raw data, at the path $.result[*].sys_id.
Request Sys ID Or Number and Custom Fields are optional parameters to run this command.
Run the Query Request Items command to obtain Request Item Sys IDs or Numbers. Request Item Sys IDs can be found in the raw data, at the path $.result[*].sys_id; Request Item Numbers can be found in the raw data, at the path $.result[*].number.
The Sys ID of the requested items to update. Sys IDs can be obtained using the Query Requested Items command.
[
"056********************05d"
]
Short Description
Optional
A short description of the updated requested item.
Apple iPhone13 0512a
Comments
Optional
The comments for the updated requested items. Comments are visible to all users, fulfillers and requesters.
New req item iphone13
Work Notes
Optional
The work notes for the updated requested item. Work notes are only visible to request fulfillers, and are not shared with requesters.
Sensitive info inside
Due Date
Optional
The due date of the updated requested item in UTC time.
2022-06-30 00:00
Request Sys ID Or Number
Optional
The request Sys ID or number of the requested items. Request Sys IDs and numbers can be obtained using the Query Requests command.
REQ*******
Custom Fields
Optional
The additional fields in JSON format to update for the requested item.
{
"urgency": "2"
}
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Update Request Items failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Request Not Found.
Error Sample Data
Update Request Items failed.
Status Code: 404.
Message: Request Not Found.
Update Requests
Updates field information of request(s) based on the Request Sys ID(s). You can obtain the Request Sys ID using the Query Requests command.
READER NOTE
The parameter Request Sys IDs is Required to run this command.
Run the Query Requests command to obtain Request Sys IDs. Request Sys IDs will be returned under $.result[*].sys_id, and Request Numbers will be returned in Raw Data $.result[*].number.
Run the Query Request Items command to obtain Request Sys IDs or Numbers. Request Sys IDs can be found in the raw data, at the path $.result[*].sys_id; Request Numbers can be found in the raw data, at the path $.result[*].number.
Input parameter Custom Fields is optional to run this command.
The Sys ID(s) of the request(s) to update. Sys IDs can be obtained using the Query Requests command.
[ "f7a******************0fc" ]
Short Description
Optional
A short description for the updated request(s).
New Request for project D. 512a
Requested For
Optional
The name, email, or Sys ID of the updated user who raised the request. If this parameter is not defined, requests will be created for the current login user.
Jon***** Wal****
Comments
Optional
The comments for the updated request(s). Comments are visible to all users, fulfillers and requesters.
test comments510
Work Notes
Optional
The work notes for the updated requests. Work notes are only visible to request fulfillers, and are not shared with requesters.
For VIP
Due Date
Optional
The due date of the updated request in UTC time.
2023-01-09 00:00
Custom Fields
Optional
The additional fields in JSON format to input into the updated requests.
{
"assigned_to": "Mic**** Ho****",
"request_state": "requested",
"stage": "requested",
"escalation": "Normal",
"upon_approval": "Proceed to Next Task"
}
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Update Request failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Request Not Found.
Error Sample Data
Update Request failed.
Status Code: 404.
Message: Request Not Found.
Update Security Incidents
Updates field information of the specified security Incidents.
READER NOTE
Sys IDs, Requested By, Assignment Group, Assigned User and Custom Fields are optional parameters to run this command.
Run the Query Security Incidents or Fetch Event command to obtain Sys IDs. For Query Security Incidents command, Sys IDs can be found in the returned raw data, at the path $.result[*].sys_id. For Fetch Event command, select the Incident Type parameter as "Security Incident". The Ticket Sys IDs can be found in the returned raw data, at the path $.result[*].sys_id.
If you have a user's email or username, you can input it into the Get User Details command to obtain the corresponding Sys IDs. The input Sys IDs for the Requested By and Assigned User parameters can can be found in the returned raw data, at the path $result[*].sys_id.
User names and user emails can be found from the ServiceNow user interface. Search for System Security, then navigate to Users and Groups > Users.
Run the Get Group Details command to obtain Assignment Groups. Group Names can be found in the returned raw data, at the path $.result[*].name, Group Sys IDs can be found in the raw data, at the path $.result[*].sys_id.
It is not recommended to use the Test Command feature with the Update Security Incidents command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:
Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.
Input
Input Parameter
Required/Optional
Description
Example
Sys IDs
Optional
The Sys IDs or numbers of the security incidents to update. Sys IDs can be obtained using the Query SecurityIncidents command.
[ "eb7*****************091" ]
Short Description
Optional
A short description for the updated security incidents.
Sec Incident 0511a
Requested By
Optional
The user name, email, or Sys ID of the requesting user. User names, emails and Sys IDs can be obtained using the Get User Details command. If this parameter is not defined, the requests will be created for the current login user. Note: The admin user cannot be the requester. If your login user account is admin, this parameter should be left empty.
Ja** Erl******
Business Impact
Optional
The impact level of the updated security incidents.
Medium
Priority
Optional
The priority level of the updated security incidents. If this field is not defined, the default priority level will be set to Low.
Moderate
Category
Optional
The category of the updated security incidents.
Unpatched Vulnerability
Assignment Group
Optional
The name or Sys ID of the group to assign the updated security incidents to. Group names and Sys IDs can be obtained using the Get Group Details command.
Problem Analyzers
Assigned User
Optional
The user name, email or Sys ID of the user assigned to the updated security incidents. User names, emails and Sys IDs can be obtained using the Get User Details command.
Note: If you input values for both the Assignment Group and Assigned User parameters, ensure that the user is in the group. Otherwise, the error message "Operation Failed" will be returned. You can use the Query Group Members command to check if the user is in the group.
Jon***** Wal****
Description
Optional
A description for the updated security incident.
Test description 0511c
Custom Fields
Optional
The additional fields in JSON format to input into the updated security incidents.
{
"comments": "510c These are my comments", "subcategory": "37"
}
File IDs
Optional
The file paths of the file source.
[
"749"
]
File Source
Optional
The file source of the file to attach. The options for file sources are:
Incident Attachment File: Manually uploaded file from Incident
Playbook File: Output from another Task
Artifact File: Ingested Artifact in an Event
Playbook File
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Update Security Incident failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Security Incident Not Found.
Error Sample Data
Update Security Incident failed.
Status Code: 404.
Message: Security Incident Not Found.
Update Tickets
Updates field information of incident(s) based on the incident ticket Sys ID(s).
READER NOTE
The parameter Ticket Sys IDs is Required to run this command.
You should already have your desired Ticket Sys IDs on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Ticket Sys IDs. The Ticket Sys IDs can be found in the raw data at the path $.result[*].sys_id.
Ensure that your input Sys ID belongs to a ticket. To do this, select the Incident Type parameter as "Incident". Note that any other format will not work.
Caller ID, Assignment Group, Assigned User and Custom Fields are optional parameters to run this command.
If you have a user's email or username, you can input it into the Get User Details command to obtain the corresponding Sys IDs. The input Sys IDs for the Caller ID and Assigned User parameters can can be found in the returned raw data, at the path $result[*].sys_id.
User names and user emails can be found from the ServiceNow user interface. Search for System Security, then navigate to Users and Groups > Users.
Run the Get Group Details command to obtain Assignment Groups. Group Names can be found in the returned raw data, at the path $.result[*].name, Group Sys IDs can be found in the raw data, at the path $.result[*].sys_id.
You will need to make sure the Assigned User is in the Assignment Group you entered if you choose to enter values for both the Assignment Group and Assigned User fields. Otherwise, D3 SOAR will return the error of “Operation Failed” error message.
It is recommended to run the Query Group Members command to check whether the user is in the group, if you choose to input values for both fields.
Input
Input Parameter
Required/Optional
Description
Example
Ticket Sys IDs
Required
The Sys ID(s) of the incident ticket(s) to update. Ticket Sys IDs can be obtained using the Fetch Event command.
[
"57e********************ed02f"
]
Short Description
Optional
A short description for the updated incident ticket(s).
Update incident through REST 0510c
Caller ID
Optional
The user name, user email, or user Sys ID of the caller. User names, user email or user Sys IDs can be obtained using the Get User Details command. If this field is not specified, the caller will be the current login user. Note: The admin user cannotbe the caller. If your login user account is admin, this parameter should be left empty.
Ja** Erl******
Impact
Optional
The impact level of the updated incident ticket(s).
Low
Urgency
Optional
The urgency level of the updated incident ticket(s).
Low
Category
Optional
The category of the updated incident ticket.
Inquiry/Help
Assignment Group
Optional
The name or Sys ID of the group to assign the updated incident ticket(s) to. Group names and Sys IDs can be obtained using the Get Group Details command.
Problem Analyzers
Assigned User
Optional
The user name, email or Sys ID of the user assigned to the updated incident ticket(s). User names, emails and Sys IDs can be obtained using the Get User Details command.
Note: If you input values for both the Assignment Group and Assigned User parameters, ensure that the user is in the group. Otherwise, the error message "Operation Failed" will be returned. You can use the Query Group Members command to check if the user is in the group.
Jon***** Wal****
Description
Optional
A description for the updated incident ticket(s).
Test description 0510c
Custom Fields
Optional
The additional fields in JSON format to input into the updated incident ticket(s).
{
"work_notes": "A test work note by Jon on 20220510."
}
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Update Ticket failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Ticket Not Found.
Error Sample Data
Update Ticket failed.
Status Code: 404.
Message: Ticket Not Found.
Test Connection
Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection. Note: If the connector uses the authentication type of OAuth2.0 Authorization Code, then you need to enable Connection Health Check to prevent the refresh token from expiring.
Input
N/A
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
SAMPLE DATA
CODE
Successful
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Test Connection failed. Failed to check the connector.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ServiceNow portal. Refer to the HTTP Status Code Registry for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Failed to establish a new connection.
Error Sample Data
Test Connection failed. Failed to check the connector.
Status Code: 400.
Message: Failed to establish a new connection.
FAQ
How do I check a connection’s login user?
Answer:
For connections using Basic Authentication, you can see the username of the login user you have configured for the connection in the corresponding configuration page.
For connections using OAuth2.0 Code authentication, you can view the login user by clicking Get Authorization > Choose your login account from the connection’s configuration page.The logged in will appear on the top right of the authorization approval page.
Where can I get the available fields’ system names?
You may find input parameters named Custom Fields in the Create Ticket, Update Tickets, Create Request, Update Requests, Create Requested Item, Update Requested Items, Create Security Incident and Update Security Incidents commands. You may also find input parameters named Record Data in the Create Record and Update Records commands.
The Custom Fields or Record Data input parameters allow you to specify other fields (not in the input parameters) that you want to enter into a ticket, request, request item, security incident and record data. You will need to input the field system name into the input parameters. There are two options available to view the system names: view them from the ServiceNow platform or use the Get Table Fields command in D3 SOAR.
Please refer to the table below for the corresponding table names and command names.
D3 SOAR Command Name
Category
Input Parameter
Table Name Search Input
Get Table Fields Command Input Value for Table Name*
Create Ticket and Update Tickets
Ticket
Custom Fields
incident
Incident
sc_task
Create Request and Update Requests
Request
Custom Fields
sc_request
sc_reques
sc_task
Create Requested Item and Update Requested Items
Requested Item
Custom Fields
sc_req_item
sc_req_item
sc_task
Create Security Incident and Update Security Incidents
Security Incident
Custom Fields
sn_si_incident
sn_si_incident
sm_order
*
(1) If two input values are listed, run the command with each value separately to obtain all field system names.
(2) For Record-related commands (i.e. Create Record and Update Records), the available field system names can be found from the table defined in the Table Name parameter in the ServiceNow platform.
Here’s an example for searching the pair of display name and system name for Ticket (can be used in Create Ticket and Update Ticket commands).
Option 1: View the Field System Names from the ServiceNow platform. Refer to the table above for the appropriate ServiceNow Table Name to search for.
Select All from the top navigation bar. Type System Definition into the filter search bar and select Tables.
Using the Tables search bar, search for the Incident table and press Enter.
Select the Incident table.
Search for your desired field (e.g. Caller).
Click the field name to check field details, the desired system name is displayed as the Column name (Column label: field display name; Column name: field system name).
Option 2: Run the Get Table Fields command
You can choose to run Get Table Fields in D3 SOAR to obtain the custom field system names. Refer to the table above for the appropriate Table Name values to use.
Log in to D3 SOAR.
Find the ServiceNow integration.
a. Navigate to Configuration on the top header menu.
b. Click on the Integration icon on the left sidebar.
c. Type ServiceNow in the search box to find the integration, then click it to select it.
Find the Get Table Fields command.
Run the command twice, using “Incident” and “Task” for the input value for the Table Name parameter separately for each instance. You will get the field Display Name with the corresponding System Name from the returned Key Fields.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.
.png)
-20241031-180734.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)
-20241031-194221.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)
-20241031-194351.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)
-20241031-194439.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)
-20241031-194541.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)
-20241031-194737.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)
-20241031-200612.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)
-20241031-200245.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)
-20241031-200413.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)
-20241031-200503.png?inst-v=3363bacf-1ba3-4a9b-b554-558cd4632ecc)