ServiceNow V2
LAST UPDATED: AUG 5, 2025
Overview
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.
ServiceNow is available for use in:
Known Limitations
Push Integration:
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.
Please refer to Limitations – ServiceNow Integration for detailed information.
Connection
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 > Application Registry > "APP Name" > Redirect URL. | https://qa8.d3securityonline.net/V140Cyber/VSOC/Auth2Callback.aspx |
Refresh Token | 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.
-20241031-180734.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
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.
-20241031-194221.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
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:
-20241031-194351.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
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:
-20241031-194439.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
Input the ServiceNow instance URL for the Server URL.
Select OAuth 2.0 Authorization Code for Authentication Type.
Input your saved Client ID (see step 8 to 13 of Configuring ServiceNow to work with D3 SOAR).
Input your saved Client Secret (see step 8 to 13 of Configuring ServiceNow to work with D3 SOAR).
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.
-20241031-194541.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
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.
-20241031-194737.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
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 checkmark appear 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.
Integration API Note
For more information about the ServiceNow API, please refer to the ServiceNow API reference.
READER NOTE
Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring ServiceNow to Work with D3 SOAR for details.
Add Ticket Attachment
Uploads an attachment to the specified 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.
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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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. | 3 |
Search Condition | Optional | The query conditions to filter the returned results. For information about the query syntax, see Operators available for filters and queries. 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
To view the sample output data for all commands, refer to this article.
Fetch Event Field Mapping
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”.-20241031-200612.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
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 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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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 match the Table Name. Otherwise, nothing will be returned.
If the input Table Name is Ticket, you will need 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. Security Incident 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
To view the sample output data for all commands, refer to this article.
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. | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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. | Problem Analyzers |
Query | Optional | The query to filter results. For more information about the query syntax, see Operators available for filters and queries. 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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 Query Tables 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
To view the sample output data for all commands, refer to this article.
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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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.
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. 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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.
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 filter and queries. 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
To view the sample output data for all commands, refer to this article.
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. | 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.
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.
Input
Input Parameter | Required/Optional | Description | Example |
Request Item Sys IDs | Required | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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.
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.
Input
Input Parameter | Required/Optional | Description | Example |
Request Sys IDs | Required | 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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.
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.
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 Security Incidents 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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.
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.
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.
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 cannot be 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
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or 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. | 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
Output Type | Description | Return Data Type |
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:
More details about an error can be viewed in the Error tab. | String |
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 |
|
Create Request and Update Requests | Request | Custom Fields | sc_request |
|
Create Requested Item and Update Requested Items | Requested Item | Custom Fields | sc_req_item |
|
Create Security Incident and Update Security Incidents | Security Incident | Custom Fields | sn_si_incident |
|
*
(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.
-20241031-200245.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
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.
-20241031-200413.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
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.
-20241031-200503.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)