OpenAPI step

Release version: Washingtondc

Updated February 1, 2024

4 minutes to read

Summarize

Summarized using AI

Summary of OpenAPI step

The OpenAPI step allows ServiceNow customers to import OpenAPI specifications of third-party outbound REST web services to build integrations. This step is part of the ServiceNow Integration Hub and enables users to create complex data object outputs from JSON response bodies based on the imported specifications.

Show full answer Show less

Key Features

Connection Alias: Facilitates the use of connection credentials without multiple configurations across environments.
API Source: Users can select from existing OpenAPI specifications or import new ones via URL or direct content.
Query Parameters: Supports manual creation and the use of input variables, including handling duplicate names.
Headers: Allows the addition of request headers, with support for duplicates, simplifying the integration process.
Attachment: Enables inclusion of request records as input variables, particularly for binary requests.
Retry Policy: Users can enable and customize retry policies for their requests.
Error Evaluation: Options to handle errors based on step status codes or messages, enhancing action flow control.

Key Outcomes

By utilizing the OpenAPI step, ServiceNow customers can efficiently integrate with external REST services, streamline their API interactions, and manage complex request and response scenarios. Additionally, they can customize error handling and retry policies to ensure robust integrations. However, users should be aware of certain limitations, such as supported media types and maximum operation limits.

Import the OpenAPI specification 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.

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

Note:

OpenAPI 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.
API Source	Option to select an OpenAPI v2.0 and v3.0 Specification used to construct the request, or select Import OpenAPI to import a new OpenAPI Specification. You can import specifications by providing a URL and credentials to the YAML or JSON, or copying and pasting content.
API Operation	Option to select an operation from the list. Available operations are provided by the OpenAPI Specification in the API Source 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, Flow Designer 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.