ServiceNow REST (Enterprise) operation

The ServiceNow REST (Enterprise) connector enables you to directly connect to ServiceNow and use a process to perform high-volume batch operations, manage attachments, and stage data using the Import Set API for enterprise-scale integrations.

A record type or object can be a project, an account, a resource, etc. Create a separate operation component for each action/object combination that your integration requires.

The ServiceNow REST (Enterprise) operations use JSON format for the request and response profiles, and support the following actions:

• Attachment - upload, download, and delete attachments from ServiceNow records.

• Batch - create or update bulk records in ServiceNow.

• Create - create and insert a record in ServiceNow.

• Delete - remove and delete a record from ServiceNow.

• Get - retrieve a record from ServiceNow.

• Import Set - transform and map import staging tables to ServiceNow entities.

• Query, Advanced Query - look up ServiceNow records based on specific search criteria.

• Update - update a record in ServiceNow.

note

If you receive an error when attempting to import a ServiceNow object (such as a 403 Forbidden authentication error), verify with ServiceNow which account permissions and roles you need. Read access to the sys\_db\_object system table may provide the required access.

Click Import Operation, then use the Import wizard to import the request and response profiles for the selected action. The following fields are available in the import wizard for their respective actions.

Object Type (Attachment) - Decide what action you'd like to perform on an attachment for a ServiceNow record.

• Download Attachment - Allows you to download attachments from ServiceNow records.
• Upload Attachment - Allows you to add attachments like images and documents to ServiceNow records like Incident, Problem, Task.
• Delete Attachment - Allows you to delete attachments from ServiceNow records.

Object Types Source (Query, Advanced Query) - Indicate whether to include Tables, Database Views or UI Views in the Object Type list.

• Tables - Allows you to query and retrieve data from a ServiceNow Table
• Database Views - Allows you to query and retrieve data from database views, which combines data from multiple tables. This offers a consolidated view without needing to execute multiple API calls across different tables.
• UI Views - Allows you to retrieve data from a UI View associated with a ServiceNow table.

Display Value (Get, Create, Batch, Update, Advanced Query, Query) - Based on this value, retrieves the display value and/or the actual value from the database. The default is to display the actual value.

Filter (Advanced Query, Query, Batch, Delete, Get, Import Set) - You can reduce the number of returned objects in your query by finding the introduced text contained in the display name for tables. The filter property is required.

Enable Dot-Walking (Advanced Query, Query) - Select this checkbox to enable the connector to access any references to other tables it may find in a given table's record and retrieve data from both using dot notation,e.g, table.name. Both single and multiple levels of dot walking are supported.

Dot Walking Depth - This conditional field appears when Enable Dot-Walking is selected. The depth must be at least 1 and no more than 5.

(UI) View (Create, Batch, Get, Update) - Enter the UI view to determine the fields returned in the response.

No response body (Create, Update) - Turn on to suppress the response body content from ServiceNow and not include information about the new record.

Input display value (Create, Update, Batch) - Turn on to treat input values as display values and manipulate them so they can be stored properly in the database. Turn off to treat input values as actual values and store them in the database without manipulation.

Operation Mode (Batch) - Selects the batch operation mode, Create or Update.

Require transformation maps (Import Set) - Select this option to include Import Set tables with at lest one active transformation map in the Object Types list. When this option is unchecked, all active Import Set tables are listed.

Split Transformation Maps results (Import Set) - When selected, the operation splits the ServiceNow response and returns one output document for each Transform Map result in the record’s results array. When this option is unchecked, the operation returns a single output document per record containing the entire results array. Use this to control output document granularity for downstream processing.

Attachment

Attachment is an action to upload, download, and delete attachments for ServiceNow records using the recordID. The Attachment action is inbound for downloading attachments and outbound for uploading or deleting them.

When using Attachment, use the Import Wizard to select which of the above actions you'd like to perform under the Object Type. When successful, the attachment will be uploaded, downloaded, or deleted; no JSON document is returned.

Batch

Batch is an outbound action to create or update multiple records in a single request.

The Batch action supports the group tracked property Response Headers. This tracked property contains the response headers returned by the service for each processed entry for the Batch action.

When using Batch, use the Import Wizard to select your Operation Mode. Select the Input Display Value checkbox if you want to manipulate your input values before they are stored in the database. When left unchecked, your input values remain unchanged and are stored in the database. The ServiceNow Batch API supports payloads up to 10MB.

Use Display Value to decide if the display value and/or the actual value should be retrieved from the database; the default is to display the actual value. Enter the fields you want to be returned in the response under UI View. Use a Filter to limit the number of results that are returned.

The Import Wizard will build the object list. After you select an object, the Wizard logs into ServiceNow and creates an object tree.

The Fields tab displays all of the fields available to select for a batch create or update request. If no fields are selected, a X-no-response-body header is added to the entry and the output document payload will be empty.

The container property com.boomi.connector.servicenow.max_batch_size describes the maximum batch output document file size. The default value is 5MB; you can override this setting up to 20MB.

When successful, a HTTP response will be returned and there will be no error messages in the JSON output file. HTTP 200 and 201 indicate successful batch update and create requests. Unsuccessful requests will be logged.

Import Set

Import Set is an outbound action to transform and map staging tables to official ServiceNow entities.

When using Import Set, use the Import Wizard to browse the object types list to view all the available staging tables in your ServiceNow instance. You can select the Require transformation maps checkbox to reduce the object types list to staging tables with at least one active transformation map; otherwise, all active staging tables are listed.

Select Split Transformation Maps to return an API response for each table separately. When enabled, every output document will appear successful despite the true ServiceNow status - use a [Decision] step to manage record states if you select this option. When left unchecked, the complete API response is returned in a single output document.

When successful, the output document(s) will return a successful HTTP status. HTTP responses besides 200 or 201 are application errors.

Get

Get is an inbound action to retrieve a record (for example, a company or incident record) from a ServiceNow database table based on the ID \(sys\_id\) of the record from the specified table.

When using Get, use the Import Wizard to browse your object definitions in real time to get any fields you have defined. After specifying the criteria, select the record to retrieve from the database. When successful, the connector retrieves information for the selected record. For example, information for a retrieved incident record includes category, cause, due date, impact, severity, and more.

Create

Create is an outbound action to create and insert a record (for example, a problem record) into a ServiceNow database table.

When using Create, use the Import Wizard to browse your object definitions in real time to get any fields you have defined. After specifying the criteria, select the record to insert into the database. When successful, the connector inserts the record. For example, information for an inserted problem record includes who the record is assigned to, a description of the problem, due date, and more.

Update

Update is an outbound action to update an existing record (for example, a problem record) in a ServiceNow database table based on the ID \(sys\_id\) of the record from the specified table.

When using Update, use the Import Wizard to browse your object definitions in real time to get any fields you have defined. Specify the criteria and select the record to update in the database. When successful, the connector updates the record. For example, information for an updated problem record includes work notes, the amount of time the problem was worked on, related incidents, and more.

Delete

Delete is an outbound action to remove and delete a record (for example, a problem record) from a ServiceNow database table. The ID \(sys\_id\) for the record to delete is required in the request profile.

When successful, the action deletes the selected record. No JSON document is returned.

Query

Query is an inbound operation to look up ServiceNow records (for example, a problem record) based on specific search criteria.

Query returns zero-to-many object records from a single Query request based on zero or more filters. After you select the Query action and use the Import Wizard, the operation component page contains configuration options to select the fields to return, add filters to limit the results, and select sorting options.

The Import Wizard builds the object list. After you select an object, the Wizard logs into ServiceNow and creates an object tree.

The Fields tab displays all of the fields for the selected table. You can select specific fields for a query, and you can also refine the query by clicking the Filters tab and define multiple expressions and group them into logical sub-groups (up to 3) to create sophisticated query logic.

For example, you can query the problem table and use the AND and OR logical operators to look up problem records for when the assigned\_to field is empty, the active field is true, and the approval field is not requested. The operator at the logical group level defines how the multiple expressions and/or logical sub-groups with that logical group are evaluated.

If you perform a Query operation without defining any filters, the operation returns all of the records in the selected table. You can sort the results of a query by specifying the field values on the Sorts tab. You can sort fields in an ascending or descending order.

You can limit the maximum number of documents to be returned by the operation in the Maximum number of results operation field. If no value is provided, the operation returns all available results. If a value is provided, it must be higher than 0.

Advanced Query

Advanced Query is an inbound operation to look up ServiceNow records (for example, a problem record) based on specific search criteria.

Advanced Query returns zero-to-many records from a single request based on a single, simple expression. After you select the Advanced Query action and use the Import Wizard, you can select the fields to look up and return in the response and add a simple query filter expression. Advanced Query returns JSON documents, supports an "is" filter, and allows you to sort the results with the query expression.

The bottom half of the Operation component page contains tabs on which you configure these options. If you do not select any fields to be returned by the query, the connector returns all fields.

You can limit the maximum number of documents to be returned by the operation in the Maximum number of results operation field. If no value is provided, the operation returns all available results. If a value is provided, it must be higher than 0.

Advanced Query supports a single filter \(\_query\_string\) that is used internally and is mapped to the sysparm\_query parameter to filter the query results. Do not add any other parameters, such as sysparm\_offset and sysparm\_limit, into the query string. Advanced Query correctly paginates the results and returns all records matching the criteria.

Options tab

Object - Displays the object type that you selected in the Import Operation wizard.

Tracking Direction - Select the document tracking direction for the operation, either Input Documents or Output Documents. This setting enables you to choose which document appears in Process Reporting. Start steps always track output documents regardless of your selection.

note

If the tracking direction is read-only, the feature to change the direction is either unavailable or the developer set the configuration to read-only. The default value you see shows you which document appears in Process Reporting.

Return Application Error Responses - This setting controls whether an application error prevents an operation from completing:

• If you clear the setting, the process stops and reports the error on the Process Reporting page.
• If you select the setting, processing continues and passes the error response to the next component processed as the connection output.

Archiving tab

See the topic Connector operation’s Archiving tab for more information.

Tracking tab

See the topic Connector operation’s Tracking tab for more information.

Caching tab

See the topic Connector operation’s Caching tab for more information.