{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":21374,"path":"integrate-applications/integration-hub/rest-request-action-designer.md","title":"REST step","bundle":null,"doc_type":null,"release":"australia","body":"\n# REST step\n\nSend an outbound REST web service request to an external system.\n\n**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.\n\nOutbound 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.\n\n## Roles and availability\n\nAvailable as an Workflow Studio action step. Users with the action\\_designer role can create a custom action with one or more action steps.\n\n## Fields\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nConnection\n\n\n\nType of connection to use. - **Define Connection Inline**: Define connection information within the action step.\n- **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.\n\n To learn more about connections and credentials, see [Introduction to credentials, connections, and aliases](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/credentials-connections-alias.md).\n\n
\n\nConnection Alias\n\n\n\nConnection & 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/credentials-connections-alias.md). The credential value is displayed as a Password \\(2 Way Encrypted\\) data pill on the data panel.\n\n **Note:** This field is available when **Use Connection Alias** is selected from the Connection list.\n\n
\n\nCredential Alias\n\n\n\nCredential 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/credentials-connections-alias.md). The credential value is displayed as a Password \\(2 Way Encrypted\\) data pill on the data panel.\n\n **Note:** This field is available when **Define Connection Inline** is selected from the Connection list.\n\n
\n\nUse MID\n\n\n\nOption 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.\n\n
\n\nBase URL\n\n\n\nBase 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 \\(\\[Omitted image \"lock-icon.png\"\\] Alt text: Lock icon\\) and entering your own.\n- If **Define Connection Inline** is selected, enter a base URL for the connection.\n\n
\n\nTest REST Step\n\n\n\nButton 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.\n\n
\n\nConnection Timeout\n\n\n\nNumber 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.\n\n**Note:** Avoid setting the **Connection Timeout** value to zero, as this may cause a stale connection.\n\n
\n\nMID Selection\n\n\n\nOption 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.\n- **Specific MID Server**: Your ServiceNow instance uses MID Server that you specify.\n- **Specific MID Cluster**: Your ServiceNow instance uses the MID Cluster that you specify.\n\nA 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/t_ConfigureAMIDServerCluster.md).\n\n\n This field is available when **Define Connection Inline** is selected from the Connection list, and **Use MID** is checked.\n\n
\n\nMID Application\n\n\n\nCapabilities 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.\n\n
\n\nCapabilities\n\n\n\nCapabilities 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.\n\n
\n\nMID Server\n\n\n\nData 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.\n\n
\n\nMID Cluster\n\n\n\nData 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.\n\n
\n\nBuild Request\n\n\n\nOption 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.\n- **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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/integration-hub/open-api-integration.md).\n- **From REST Message**: Import a Platform REST message. For more information, see [Import a REST message into a REST step](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/integration-hub/import-rest-message-step.md).\n\n
\n\nAPI Source\n\n\n\nOption 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.\n\n **Note:** This field is available when you select **From OpenAPI specification** from the Build Request list.\n\n
\n\nAPI Operation\n\n\n\nOption to select an operation from the list. Available operations are provided by the OpenAPI Specification in the **API Source** field.\n\n **Note:** This field is available when you select **From OpenAPI specification** from the Build Request list.\n\n
\n\nREST Message\n\n\n\nName 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.\n\n
\n\nREST Message Function\n\n\n\nName 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.\n\n
\n\nImport REST Message\n\n\n\nButton to import the REST message. **Note:** This field is available when you select a REST message from the **REST Message** field.\n\n
\n\nResource Path\n\n\n\nPath for the resource.\n\n
\n\nHTTP Method\n\n\n\nHTTP method used to process the request.- **GET**\n- **POST**\n- **PUT**\n- **PATCH**\n- **DELETE**\n\n
\n\nQuery Parameters\n\n\n\nName-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.\n\n 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.\n\n **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.\n\n
\n\nHeaders\n\n\n\nHeaders to send with the request. You can create headers manually, or drag input variables into the parameter fields, and then assign a value.\n\n 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.\n\n **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.\n\n
\n\nRequest Type\n\n\n\nFormat of the request. Options include.- **Text**: A request in JSON, XML, or other text format.\n- **Binary**: A request in a binary file format.\n- **Multipart**: A request consisting of multiple content types.\n- **Form URL-Encoded**: A request in a URL-encoded query.\n\n **Note:** This field is editable when the **HTTP Method** is **POST**, **PUT**, **PATCH**, or **DELETE**.\n\n
\n\nRequest Body \\[Text\\]\n\n\n\nBody 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.\n\n
\n\nAttachment\n\n\n\nAttachment 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.\n\n
\n\nName, Part Type, Value\n\n\n\nContent 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 \\(\\[Omitted image \"flow-designer-inline-script-icon.png\"\\] Alt text: Toggle inline scripting icon\\) and editing the script. For more information about inline scripting, see .\n\n - **Name**:The name of the part. It can be any valid string.\n- **Part Type**: The type of the part. Select either **Text** or **File**.\n - **Text**:The text for the part. Once **Text** is selected, you can specify the content type.\n - **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.\n - For **Set Filename**, select **From Attachment** to use the attached record’s file name, or select **From Filename input** to enter your own.\n - 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.\n- **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.\n\n**Note:** These fields are available when you select **Multipart** from the Request Type list.\n\n
\n\nName, Value\n\n\n\nContent 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\\(\\[Omitted image \"flow-designer-inline-script-icon.png\"\\] Alt text: Toggle inline scripting icon\\) and editing the script. For more information about inline scripting, see .**Note:** This field is available when you select **Form URL-Encoded** from the Request Type list.\n\n
\n\nEnable Retry Policy\n\n\n\nOption to enable the retry policy. For more information, see [Retry policy](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/build-workflows/retry-policy.md).\n\n
\n\nOverride Default Policy for Alias\n\n\n\nOption to override the default retry policy. This check box is not applicable when **Define Connection Inline** is selected from the Connection list.\n\n
\n\nRetry Policy\n\n\n\nDefault 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.\n\n
\n\nSave As Attachment\n\n\n\nOption to specify whether to save the response as a record in the Attachment \\[sys\\_attachment\\] table.\n\n
\n\nAttachment File Name\n\n\n\nName of the attachment created by the REST response. For example, `rest-response.txt`.**Note:** This field is available when **Save As Attachment** is selected.\n\n
\n\nAttachment File Record\n\n\n\nTarget 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.\n\n
## Action error evaluation\n\n- **If this step fails**\n\n Data type: **Choice**\n\n 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 .\n\n\n## REST response size limits\n\nBy 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.\n\n## Parsing a REST response\n\nREST 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/build-workflows/javascript-step-action-designer.md) to parse the structured data into variables to use elsewhere in the action or in a flow. There is also an [XML parser step](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/integration-hub/xml-parser-step-action-designer.md) to parse a response body that's in an XML format.\n\nThe general strategy to get extracted data from the response is to do the following.\n\n1. Review the response body to select the data to return.\n2. Create input and output variables in the Script step.\n - Create an input variable to pass in the Response Body from the REST step.\n - Create output variables to return data from the response.\n3. Create a script to parse and map data.\n - Use the `JSON.parse()` method in a Script step to parse a JSON response body.\n - Map the parsed data to the output variables.\n4. Create action outputs for the output variables to make the data available to a flow.\n\nFor a detailed example, see the section on Parsing a REST Response in the [REST in IntegrationHub developer training \\(Zurich\\)](https://developer.servicenow.com/dev.do#!/learn/courses/australia/app_store_learnv2_rest_australia_rest_integrations/app_store_learnv2_rest_australia_rest_in_integration_hub/app_store_learnv2_rest_australia_rest_in_integration_hub_objectives).\n\n- **[Import a REST message into a REST step](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/integration-hub/import-rest-message-step.md)** \nTransfer data from an existing Platform REST message into a REST step.\n\n**Parent Topic:**[Integration steps](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/integration-hub/integration-steps.md)\n\n"}}