ServiceNow

1. Overview

ServiceNow is a leading cloud platform that provides a range of solutions, including IT Service Management (ITSM), IT Operations Management (ITOM), and IT Business Management (ITBM), to help enterprises automate digital workflows.

With GoInsight's ServiceNow node, you can seamlessly integrate powerful IT service management capabilities into your automated workflows. You can manage the entire lifecycle of core resources within ServiceNow, including:

• Incident Management: Automate the creation, updating, querying, and deletion of incidents.
• User Management: Perform create, update, query, and delete operations on user accounts.
• Generic Record Management: Create, read, update, and delete records in any ServiceNow data table.
• Attachment Management: Upload, download, and delete attachments associated with records.
• Data Querying: Flexibly query various system resources such as business services, configuration items, departments, user groups, and roles.

2. Prerequisites

Before using this node, you need to meet the following conditions:

• You must have a valid ServiceNow instance account.
• The account you use must have the appropriate roles and permissions to perform the required actions via the REST API (e.g., creating incidents, managing users).

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on core resources within ServiceNow, such as incidents, users, attachments, and generic table records. The table below summarizes all supported operations:

Operation Details

Create a Table Record

Creates a record in a specified table in ServiceNow.

Input Parameters:

• TableName: The name of the table where the record will be created.
• RecordData: The fields of the record to be created, represented in JSON format. (e.g., {"short_description": "Sample record created via API", "priority": "3"})

Output:

• RecordID (string): The system ID (sys_id) of the created record.
• StatusCode (number): Result code, -1 for parameter validation error, 201 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Create a User

Creates a user in ServiceNow.

Input Parameters:

• UserData: The fields of the user to be created, in JSON format. (e.g., {"user_name": "john.doe", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "123-456-7890", "active": "true", "department": "IT", "description": "Software Developer" })

Output:

• UserID (string): The ID of the created user.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Create an Incident

Creates an incident in ServiceNow.

Input Parameters:

• IncidentData: The fields of the incident to be created, in JSON format. (e.g., {"short_description": "User unable to access email", "caller_id": "employee@example.com", "category": "email", "subcategory": "outlook", "urgency": "2", "impact": "2", "assignment_group": "IT Support", "assigned_to": "support_agent" })

Output:

• IncidentID (string): The system ID (sys_id) of the created incident.
• StatusCode (number): Result code, -1 for parameter validation error, 201 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Delete a Table Record

Deletes a record from a specified table in ServiceNow.

Input Parameters:

• TableName: The name of the table from which to delete the record.
• RecordSysId: The system ID (sys_id) of the record to delete.

Output:

• Success (bool): True if the deletion was successful, otherwise False.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Delete a User

Deletes a user from ServiceNow.

Input Parameters:

• UserSysId: The system ID (sys_id) of the user to delete.

Output:

• Success (bool): True if the deletion was successful, otherwise False.
• StatusCode (number): Result code, -1 for parameter validation error, 204 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Delete an Attachment

Deletes an attachment from ServiceNow.

Input Parameters:

• AttachmentSysId: The system ID (sys_id) of the attachment to delete.

Output:

• Success (bool): True if the deletion was successful, otherwise False.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Delete an Incident

Deletes an incident from ServiceNow.

Input Parameters:

• IncidentSysId: The system ID (sys_id) of the incident to delete.

Output:

• Success (bool): True if the deletion was successful, otherwise False.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many Attachments

Gets multiple attachments from ServiceNow.

Options:

• Query: A query string to filter attachments (e.g., file_nameLIKEexample).

Output:

• Attachments (object-array): A list of retrieved attachment objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many Business Services

Gets multiple business services from ServiceNow.

Options:

• Query: A query string to filter business services (e.g., nameLIKEservice).

Output:

• BusinessServices (object-array): A list of retrieved business service objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many Configuration Items

Gets multiple configuration items from ServiceNow.

Options:

• Query: A query string to filter configuration items (e.g., nameLIKEcomputer).

Output:

• ConfigurationItems (object-array): A list of retrieved configuration item objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many Departments

Gets multiple departments from ServiceNow.

Options:

• Query: A query string to filter departments (e.g., nameLIKEengineering).

Output:

• Departments (object-array): A list of retrieved department objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many Dictionaries

Gets multiple dictionary entries from ServiceNow.

Options:

• Query: A query string to filter dictionary entries (e.g., nameLIKEsys_user).

Output:

• Dictionaries (object-array): A list of retrieved dictionary objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many Incidents

Gets multiple incidents from ServiceNow.

Options:

• Query: A query string to filter incidents (e.g., short_descriptionLIKEemail^active=true).

Output:

• Incidents (object-array): A list of retrieved incident objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many Table Records

Gets multiple records from a specified table in ServiceNow.

Input Parameters:

• TableName: The name of the table from which to retrieve records.

Options:

• Query: A query string to filter records (e.g., short_descriptionLIKEemail^active=true).

Output:

• Records (object-array): A list of retrieved record objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many User Groups

Gets multiple user groups from ServiceNow.

Options:

• Query: A query string to filter user groups (e.g., nameSTARTSWITHdev).

Output:

• Groups (object-array): A list of retrieved user group objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many User Roles

Gets multiple user roles from ServiceNow.

Options:

• Query: A query string to filter user roles (e.g., nameSTARTSWITHadmin).

Output:

• Roles (object-array): A list of retrieved user role objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get Many Users

Gets multiple users from ServiceNow.

Options:

• Query: A query string to filter users (e.g., user_nameSTARTSWITHjohn^active=true).

Output:

• Users (object-array): A list of retrieved user objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get a Table Record

Gets a single record from a specified table in ServiceNow.

Input Parameters:

• TableName: The name of the table from which to retrieve the record.
• RecordSysId: The system ID (sys_id) of the specific record to retrieve.

Output:

• Records (object-array): A list of the retrieved record object.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get a User

Gets a single user from ServiceNow.

Input Parameters:

• UserSysId: The system ID (sys_id) of the specific user to retrieve.

Output:

• Users (object-array): A list of the retrieved user object.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get an Attachment

Gets a single attachment from ServiceNow.

Input Parameters:

• AttachmentSysId: The system ID (sys_id) of the attachment to retrieve.

Options:

• DownloadPath: The local path to save the downloaded file. If not provided, the attachment content will be returned as a Base64 encoded string.

Output:

• Attachment (object): The metadata and content of the attachment.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Get an Incident

Gets one or more incidents from ServiceNow.

Input Parameters:

• IncidentSysId: The system ID (sys_id) of the specific incident to retrieve.

Output:

• Incidents (object-array): A list of retrieved incident objects.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Upload an Attachment

Uploads an attachment to a record in ServiceNow.

Input Parameters:

• TableName: The name of the table to attach the file to (e.g., sys_user, incident).
• TableSysId: The system ID (sys_id) of the record to attach the file to.
• FilePath: The local path of the file to upload (e.g., /path/to/your/file.txt).

Options:

• FileName: The name to be assigned to the file in ServiceNow. If not provided, the original filename will be used.

Output:

• AttachmentID (string): The system ID (sys_id) of the uploaded attachment.
• StatusCode (number): Result code, -1 for parameter validation error, 201 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Update a Table Record

Updates a record in a specified table in ServiceNow.

Input Parameters:

• TableName: The name of the table where the record will be updated.
• RecordSysId: The system ID (sys_id) of the record to update.
• RecordData: The fields of the record to be updated, in JSON format. (e.g., {"state": "In Progress", "assigned_to": "john.doe", "work_notes": "Updating the record via REST API"})

Output:

• RecordID (string): The system ID (sys_id) of the updated record.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Update a User

Updates a user in ServiceNow.

Input Parameters:

• UserSysId: The system ID (sys_id) of the user to update.
• UserData: The fields of the user to be updated, in JSON format. (e.g., {"first_name": "John", "last_name": "Smith", "email": "john.smith@example.com", "phone": "555-555-5555", "active": "true" })

Output:

• UserID (string): The system ID (sys_id) of the updated user.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

Update an Incident

Updates an incident in ServiceNow.

Input Parameters:

• IncidentSysId: The system ID (sys_id) of the incident to update.
• IncidentData: The fields of the incident to be updated, in JSON format. (e.g., {"state": "In Progress", "assigned_to": "john.doe", "work_notes": "Investigating the issue."})

Output:

• IncidentID (string): The system ID (sys_id) of the updated incident.
• StatusCode (number): Result code, -1 for parameter validation error, 200 for success, others are HTTP status codes from the API or 500 for network errors.
• ErrorMessage (string): Error description, empty string if there is no error.

5. Example Usage

This section will guide you through creating a simple workflow to automatically create a new incident in your ServiceNow instance.

Workflow Overview

A basic workflow consists of three nodes: Start -> Create an Incident -> Answer.

Step-by-Step Guide

1. Add Tool Node:
   • On the workflow canvas, click the "+" sign to add a new node.
   • In the pop-up panel, select the "Tools" tab.
   • In the tool list, find and select Servicenow.
   • In the list of supported operations for Servicenow, click Create an Incident, which will add the corresponding node to the canvas.
2. Configure Node:
   • Click the newly added Create an Incident node to open its configuration panel on the right.
   • Credential Configuration: At the top of the panel, find the credential field. Click the dropdown menu and select your pre-configured Servicenow credential.
   • Parameter Entry: Find the IncidentData input box. This is a JSON-formatted parameter used to define the details of the new incident. You need to fill in the necessary fields according to your ServiceNow instance's configuration. Here is an example:
   • short_description: A brief description or title of the incident.
   • caller_id: The user reporting the incident (usually their email or username).
   • category, subcategory: The classification of the incident.
   • urgency, impact: The urgency and impact of the incident, often used to calculate priority.
   • assignment_group: The team responsible for handling this incident.
3. Run and Validate:
   • Once all required parameters are correctly filled in, the error indicator in the top-right corner of the workflow canvas will disappear.
   • Click the "Run" button in the top-right corner to execute the workflow.
   • After successful execution, you can click the log icon in the top-right corner to view the node's detailed input and output. In the output, you should see an IncidentID, which indicates that the incident was created successfully. You can use this ID to find and verify the newly created incident in ServiceNow.

Final Workflow Display

After completing the steps above, your entire workflow is configured. Clicking "Run" will successfully create a new incident in your ServiceNow instance.

6. FAQs

Q: Why am I receiving a 401 Unauthorized or 403 Forbidden error?

A: This is usually related to permissions. Please check the following:

• Credential Information: Ensure that the ServiceNow credentials (username, password, instance address) configured in GoInsight are completely correct.
• User Permissions: Confirm that the ServiceNow user account used for the API call has the necessary roles and permissions to perform the corresponding actions (e.g., the itil role is often required to create incidents).
• Network Access: Check if there are any network firewalls or IP access control policies restricting access from the GoInsight server to your ServiceNow instance.

Q: How do I find the correct TableName for the Create a Table Record operation?

A: You can find the name of a table in your ServiceNow instance in the following ways:

• System Dictionary: Navigate to System Definition > Dictionary. Here you can search for and find records of all tables and their exact names.
• URL Inspection: Navigate to the list of records you want to operate on (e.g., the list of all change requests) and look at the URL in your browser's address bar. The URL often contains the table name, for example, .../nav_to.do?uri=%2Fchange_request_list.do, where the table name is change_request.

Q: The JSON data I provided in RecordData or IncidentData is causing an error. How should I troubleshoot this?

A: When encountering errors related to JSON data, please check the following:

• JSON Syntax: Ensure your JSON string is perfectly formatted. Check for missing commas, extra commas, unclosed quotes, or curly braces. You can use an online JSON validator to check the syntax.
• Field Names: Confirm that all field names (keys) used in the JSON exist in the target ServiceNow table and are spelled correctly.
• Field Values: Ensure that the value types provided for each field are correct (e.g., a reference field may require a sys_id instead of a display name).

7. Official Documentation

For a more in-depth understanding of ServiceNow's API capabilities, please refer to its official documentation:

Official ServiceNow REST API Documentation