OpenAPI/Postman step

Import the OpenAPI specification or a Postman collection of a third-party outbound REST web service and build an integration to the web service. The request details for the underlying REST API operation are derived from the OpenAPI specification or Postman collection.

For JSON output response body, the system creates a complex data object output from the OpenAPI specification or Postman collection.

Note:

OpenAPI/Postman 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.

Roles and availability

Available as an Action Designer action step. Users with the action_designer and open_api_admin, or admin roles can create a custom action with one or more action steps.

Fields

Field	Description
Connection Alias	Connection & Credential alias record that the system uses to run the action step. Users with the action_designer and connection_admin, or admin roles can select an associated Connection alias 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.
Base URL	Base URL from the Connection Alias for the REST request.
Toggle Advanced View	Option to view or hide the request details. When enabled, you can view and configure the resource path, HTTP method, query parameters, headers, and action outputs of the request.
API Source	Option to select an API from the list of available imported APIs.
Import Spec	Option that allows you to import an OpenAPI (v2.0 or v3.0) specification or a Postman collection (version 2.0.0 or 2.1.0). You can import an OpenAPI specification or Postman collection by providing a URL and credentials to the specification or collection, or manually copying and pasting JSON content.
API Operation	Option to select an operation from the list. Available operations are provided by the OpenAPI Specification or Postman collection in the API Source field.
Save As Attachment	Option to specify whether to save the response as a record in the Attachment [sys_attachment] table.
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.
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.
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.

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.

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.

Known limitations

Create a OpenAPI step from an OpenAPI Specification with these limitations.

Request body media types

The request body only supports JSON media types.

Note:

A string type output object is created when the OpenAPI schema has additionalProperties or no properties.

OpenAPI 3.0 components

OpenAPI 3.0 adds new components to Swagger 2.0 to describe an API in further detail. OpenAPI support in the OpenAPI step supports some, but not all of these components. The OpenAPI step does not currently support these components.

• Schema Object: additionalProperties properties
• Discriminator Object
• Info object: termsOfService, contact, license fields
• Example Object
• Link Object
• Callback Object
• Security Scheme Object
• Security Requirements Object
• Tag Object
• External Documentation Object
• Server Object
• Specification extensions
• Recursive references

More information on these components is available in the OpenAPI documentation. See OpenAPI Specification.

Maximum number of operations supported

The number of API operations is limited to 500 by default. However, using the system property glide.rest.openapi.max_operation_limit, you can configure the number of operations from 1 through 1000.