Send an outbound REST web service request to an external system.

Note: REST step is not available in the base system and requires the ServiceNow® Integration Hub subscription. After the required plugin is activated, the step is visible under Integrations.

Outbound REST web service is a platform feature that enables you to retrieve, create, update, or delete data on a web services server that supports the REST architecture.

Roles and availability

Available as an Workflow Studio action step. Users with the action_designer role can create a custom action with one or more action steps.

Fields

Field Description
Connection Type of connection to use.
  • Define Connection Inline: Define connection information within the action step.
  • Use Connection Alias: Define connection information using the Connection Alias table. Using an alias eliminates the need to configure multiple credentials and connection information profiles when using an action in multiple environments. Likewise, if the connection information changes, you don't need to update your custom action.

To learn more about connections and credentials, see Introduction to credentials, connections, and aliases.
Connection Alias

Connection & Credential alias record that the system uses to run the action step. Users with the flow_designer or admin role can create or select an associated Connection record. Using an alias eliminates the need to configure multiple credentials and connection information profiles when using an action in multiple environments. Likewise, if the connection information changes, you don't need to update your custom action. To learn more about connections and credentials, see credentials, connections, and aliases. The credential value is displayed as a Password (2 Way Encrypted) data pill on the data panel.

Note: This field is available when Use Connection Alias is selected from the Connection list.
Credential Alias

Credential alias that the system uses to run the action step. Users with the flow_designer or admin role can create or select an associated Connection record. Using an alias eliminates the need to configure multiple credentials when using an action in multiple environments. Likewise, if the credential information changes, you don't need to update your custom action. To learn more about connections and credentials, see credentials, connections, and aliases. The credential value is displayed as a Password (2 Way Encrypted) data pill on the data panel.

Note: This field is available when Define Connection Inline is selected from the Connection list.
Use MID Option to use a ServiceNow® MID Server to run the REST step. Select this check box to display the MID Application and Capabilities fields.
Note: The system doesn't log REST request, response, and parameter runtime data sent via a MID server in the same way that Outbound web services logging occurs. Instead, you can view this data in the Flow execution details.
Base URL Base URL for the REST request.
  • If Use Connection Alias is selected, this field displays the base URL associated with the alias. You can override the base URL by clicking the lock icon (Lock icon) and entering your own.
  • If Define Connection Inline is selected, enter a base URL for the connection.
Test REST Step Button to test the REST step. To test, select the Test REST Step button. Enter any required input values and select the Run Test button. After the test runs, any step outputs or error messages are displayed in the Test Results section of the test window.
Connection Timeout
Number of milliseconds the system waits for a successful host connection. If the step does not make a successful connection during this time, the connection request times out. If Define Connection Inline is selected, enter a timeout value for the connection. Leave this field empty to use the system default connection timeout value.
Note: Avoid setting the Connection Timeout value to zero, as this may cause a stale connection.
MID Selection Option to select a specific MID Server or MID Cluster. Choose any one of the following options.
  • Auto-Select MID Server: Your ServiceNow instance selects the MID Server without manual input.
  • Specific MID Server: Your ServiceNow instance uses MID Server that you specify.
  • Specific MID Cluster: Your ServiceNow instance uses the MID Cluster that you specify.

    A MID Cluster is a group of MID Servers that enables your ServiceNow instance to handle multiple integrations, and improve integration speed. For more information, see Configure a MID Server cluster.

This field is available when Define Connection Inline is selected from the Connection list, and Use MID is checked.
MID Application Capabilities the MID Server must support to be eligible for selection. The system runs the action step from a MID Server that supports the selected capabilities. This field is available when Define Connection Inline is selected from the Connection list, Use MID check box is enabled, and Auto-Select MID Server is selected from the MID Selection list.
Capabilities Capabilities the MID Server must support to be eligible for selection. The system runs the action step from a MID Server that supports the selected capabilities. This field is available when Define Connection Inline is selected from the Connection list, Use MID check box is enabled, and Auto-Select MID Server is selected from the MID Selection list.
MID Server Data pill of the required MID Server. This field is available when Define Connection Inline is selected from the Connection list, Use MID check box is enabled, and Specific MID Server is selected from the MID Selection list.
MID Cluster Data pill for the MID Cluster you want to use. This field is available when Define Connection Inline is selected from the Connection list, Use MID is checked, and Specific MID Cluster is selected from the MID Selection list.
Build Request Option to create the request manually, import an OpenAPI Specification, or import a REST message.
  • Manually: Create action inputs and complete the REST step form manually.
  • From OpenAPI specification: Import an OpenAPI Specification to generate action inputs and complete the REST step form. For more information, see OpenAPI support in the REST step.
  • From REST Message: Import a Platform REST message. For more information, see Import a REST message into a REST step.
API Source

Option to select an OpenAPI Specification used to construct the request, or select Import OpenAPI to import a new OpenAPI Specification. You can import specifications by providing a URL to the YAML or JSON, or copying and pasting content.

Note: This field is available when you select From OpenAPI specification from the Build Request list.
API Operation

Option to select an operation from the list. Available operations are provided by the OpenAPI Specification in the API Source field.

Note: This field is available when you select From OpenAPI specification from the Build Request list.
REST Message Name of the REST message to import. Select a REST message from the list.
Note: This field is available when you select From REST Message from the Build Request list.
REST Message Function Name of the function to import from REST message. The available options are determined by the HTTP methods associated with the selected REST message.
Note: This field is available when you select From REST Message from the Build Request list.
Import REST Message Button to import the REST message.
Note: This field is available when you select a REST message from the REST Message field.
Resource Path Path for the resource.
HTTP Method HTTP method used to process the request.
  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
Query Parameters

Name-value pairs to pass to the REST endpoint. You can create these parameters manually, or drag input variables into the parameter fields, and then assign a value.

Support REST step requests that contain duplicate query parameter names. If you create a REST request that contains duplicate query parameter names, Workflow Studio adds the query parameters to the request in the same order as you defined them.

Note: When importing an OpenAPI Specification, the system adds all parameters and headers present in the specification to the REST step. Review the final REST step values and remove parameters you do not want to send in the request. For example, if the API accepts content type headers for both JSON and XML, the system adds both headers to the REST step. Remove one of the headers depending on the content type you want to receive in the response.
Headers

Headers to send with the request. You can create headers manually, or drag input variables into the parameter fields, and then assign a value.

Support REST step requests that contain duplicate request headers. If you create a REST request that contains duplicate request headers, the headers are sent in the same order as you defined them.

Note: When importing an OpenAPI Specification, the system adds all parameters and headers present in the specification to the REST step. Review the final REST step values and remove parameters you do not want to send in the request. For example, if the API accepts content type headers for both JSON and XML, the system adds both headers to the REST step. Remove one of the headers depending on the content type you want to receive in the response.
Request Type Format of the request. Options include.
  • Text: A request in JSON, XML, or other text format.
  • Binary: A request in a binary file format.
  • Multipart: A request consisting of multiple content types.
  • Form URL-Encoded: A request in a URL-encoded query.
Note: This field is editable when the HTTP Method is POST, PUT, PATCH, or DELETE.
Request Body [Text] Body of the request in JSON or XML format. The flow execution details display the response body as either a link to the embedded text viewer or the sys_id of the attachment record containing the response.
Note: This field is editable if you select Text from the Request Type list.
Attachment Attachment record that contains the request. You can look up or create this record in a prior step and define it as an input variable. Create it by using the JSONStreamingBuilder and XMLStreamingBuilder APIs in the Script step.
Note: This field is available when you select Binary from the Request Type list.
Name, Part Type, Value

Content of a multipart request. For each part, specify its name, part type, and value either using the fields individually or using an inline script for all the parts. You can specify the multipart values by clicking the toggle scripting icon (Toggle inline scripting icon) and editing the script. For more information about inline scripting, see Inline scripts.

  • Name:The name of the part. It can be any valid string.
  • Part Type: The type of the part. Select either Text or File.
    • Text:The text for the part. Once Text is selected, you can specify the content type.
    • File:The file for the part. When File is selected, the Value must be the sys_id of the attachment record containing the content. You can look up this record in a prior step or define it as an input value. Once File is selected, you can specify the file name and content type.
      • For Set Filename, select From Attachment to use the attached record’s file name, or select From Filename input to enter your own.
      • For Set Content Type, select From Attachment to use the attached record's content type, or select From Content Type input to enter your own.
  • Value: The content of the part. For text, the value is the text content. For a file, the value is the sys_id of the attachment record containing the content.
Note: These fields are available when you select Multipart from the Request Type list.
Name, Value Content of a form URL-encoded request. Specify each part of the URL-encoded request with a name-value pair using the fields individually or using an inline script for all parts. You can specify the form URL-encoded values inline script by clicking the toggle scripting icon(Toggle inline scripting icon) and editing the script. For more information about inline scripting, see Inline scripts.
Note: This field is available when you select Form URL-Encoded from the Request Type list.
Enable Retry Policy Option to enable the retry policy. For more information, see Retry policy.
Override Default Policy for Alias Option to override the default retry policy. This check box is not applicable when Define Connection Inline is selected from the Connection list.
Retry Policy Default retry policy associated with Connection Alias. If Override Default Policy for Alias is selected, you can override the default retry policy and select another existing retry policy based on your requirement.
Save As Attachment Option to specify whether to save the response as a record in the Attachment [sys_attachment] table.
Attachment File Name Name of the attachment created by the REST response. For example, rest-response.txt.
Note: This field is available when Save As Attachment is selected.
Attachment File Record Target record to which the attachment is associated. The target record must be a data pill of type Record. For example, a specific incident record. You can look up this record in a prior step or define it as an input variable. The flow execution details display the sys_id of the associated record.
Note: This field is available when Save As Attachment is selected.

Action error evaluation

If this step fails
Data type: Choice

Option to continue running the next step or go to error evaluation. To use the step status code or message for a custom action error condition, see Action error evaluation.

REST response size limits

By default, the system limits the size of REST responses that are not saved as attachments to 5 MB. Direct REST responses that exceed this limit generate an error. To support larger response sizes, either save the response as an attachment or increase the response size limit with the glide.pf.rest.response_payload_max_size system property. This system property supports a maximum value of 10240 KB, which limits the REST response to 10 MB in size.

Parsing a REST response

REST API calls return data in the Response Body. The response body data is usually structured in JSON or XML format. You can use a Script step to parse the structured data into variables to use elsewhere in the action or in a flow. There is also an XML parser step to parse a response body that's in an XML format.

The general strategy to get extracted data from the response is to do the following.
  1. Review the response body to select the data to return.
  2. Create input and output variables in the Script step.
    • Create an input variable to pass in the Response Body from the REST step.
    • Create output variables to return data from the response.
  3. Create a script to parse and map data.
    • Use the JSON.parse() method in a Script step to parse a JSON response body.
    • Map the parsed data to the output variables.
  4. Create action outputs for the output variables to make the data available to a flow.
For a detailed example, see the section on Parsing a REST Response in the REST in IntegrationHub developer training (Zurich).