# OpenAPI default connection fields reference

When using the OpenAPI connector to create custom connectors, you control the fields end users see when setting up a connection.

This guide serves as a reference for the default connection fields in the universal OpenAPI connector.

# Field reference documentation

Each connection field in the OpenAPI connector has its own section in this guide. In each section, you'll find the following info:

Description	A description of the field
UI name	The name of the field as it displays in Workato, ex: Authentication method
Source code name	The name of the field in the connector's source code, ex: `auth_method`
Required?	Whether the field is required or not

# Required fields

While you can customize connection fields, the following fields must be present in connection.fields or adjust_connection to successfully configure a custom OpenAPI connector:

Authentication method (auth_method)
Basic auth user (basic_auth_user) *
Document content (definition_content) *
OpenAPI document source (definition_mode)
Document URL (definition_url) *
Header authorization (auth_headers) *
OAuth2 authorization URL (authorization_url) *
OAuth2 token URL (token_url) *
Client ID (client_id) *
Client Secret (client_secret) *
Username (username) *
Password (username) *
Query param authorization (query_params) *
Server URL (base_url)

* indicates the field is dependent on another field. Refer to the documentation for the field for more info.

# Allow long field hints

If set to No, object hints will be stripped to a single paragraph. The default is No.

UI name	Allow long field hints
Source code name	advanced.allow_multi_paragraph_hint
Required?	No

# Authentication method

THIS IS A REQUIRED FIELD.

The authentication method the connection uses. The value of this field determines what other values the user must provide for authentication:

none (no other input required)
basic (see Basic auth user and Basic auth password)
header (see Header authorization)
query (see Query param authorization)
oauth2_client_credentials (see OAuth2 token URL, How does the API require credentials to be sent to request a token?, Client ID, Client Secret and Scopes)
oauth2_authorization_code (see OAuth2 authorization URL, OAuth2 token URL, How does the API require credentials to be sent to request a token?, Client ID, Client Secret and Scopes)
oauth2_resource_owner_password (see OAuth2 token URL, Client ID, Client Secret, Username, Password and Scopes)

Refer to the OpenAPI authentication guide for more info about supported authentication methods.

UI name	Authentication method
Source code name	auth_method
Required?	Yes

# Basic auth user

THIS IS A REQUIRED FIELD.

The name of the application user/account.

UI name	Basic auth user
Source code name	basic_auth_user
Required?	Yes, if Authentication method is set to `basic`

# Basic auth password

The password of the user. An alternative to your password would be an API key or API token, retrieved from your account settings.

This should be kept secret.

UI name	Basic auth password
Source code name	basic_auth_password
Required?	No

# Schema depth limit

Define the maximum depth for nested fields to be includes in the input and output schema descriptions.

UI name	Schema depth limit
Source code name	advanced.max_schema_depth
Required?	No

Limit nested fields

If your input or output schema contains too many nested fields, it may be difficult to use the connector.

For example, a company object has a property of parentCompany which is another company object. Further, the parent company may also have another parentCompany.

Schema depth limit and Schema recursion limit allows you to prevent this nesting from continuing indefinitely.

# Schema recursion limit

Define the maximum depth recursive schema definitions to be included in input and output schema descriptions.

UI name	Schema recursion limit
Source code name	advanced.max_recursion_depth
Required?	No

Limit nested fields

If your input or output schema contains too many nested fields, it may be difficult to use the connector.

For example, a company object has a property of parentCompany which is another company object. Further, the parent company may also have another parentCompany.

Schema depth limit and Schema recursion limit allows you to prevent this nesting from continuing indefinitely.

# Document content

THIS IS A REQUIRED FIELD.

Content of the OpenAPI document. Format is either JSON or YAML. Supports OpenAPI v2 and v3.

UI name	Document content
Source code name	definition_content
Required?	Yes, when OpenAPI document source is set to `content`

# Documentation links

Link to the application documentation, user guides, or company web site. This documentation link will be provided in the help text of your connector's triggers or actions.

UI name	Documentation link
Source code name	advanced.documentation_href
Required?	No

# OpenAPI document source

THIS IS A REQUIRED FIELD.

Defines how to provide the OpenAPI document to the connector. The preferred approach is to load it from a URL. Otherwise, copy and paste the contents of the file.

The value of this field determines what other values the user must provide. Must be one of the following:

url (see Document URL)
content (see Document content)

UI name	OpenAPI document source
Source code name	definition_mode
Required?	Yes

# Document URL

THIS IS A REQUIRED FIELD.

This URL must be publicly accessible at all time. Any future changes to the document itself appear automatically in the Workato recipe editor. The document can be in either JSON or YAML format. Supports OpenAPI v2 and v3.

UI name	Document URL
Source code name	definition_url
Required?	Yes, when OpenAPI document source is set to `url`

# External documentation links

When defined, allows object field descriptions to link to external websites like API references or documentation.

Refer to the Customizing OpenAPI user interfaces guide for more info and examples.

UI name	External documentation links
Source code name	advanced.external_links
Required?	No

# Filter API endpoints

Defines rules for filtering endpoint.

UI name	Filter API endpoints
Source code name	advanced.endpoint_filter_rules
Required?	No

# Sample

{
  ...
  "advanced" => {
    "endpoint_filter_rules" => [
      { 
        "type" => "include", 
        "operation_id" => "createPet"
      },
      ...
    ]
  }
  ...
}

API endpoint filter rules

You can use include or exclude filter rules.

You can also filter based on the HTTP method (http_method), Tag (tag), Operation ID (operation_id), or URL path (Path).

# Header authorization

A list of headers to be added to API requests. Used for applications that require additional headers outside of the usual username and password or API key, or if you want to customize the headers sent in the request. Header authentication can be used when you have a generated token ready for use.

Examples:
API-Key: 1234567890 X-API-Token: abc123

UI name	Header authorization
Source code name	auth_headers
Required?	Yes, when Authentication method is set to `header`

# Ignore request fields

Defines the specific request fields the connector should ignore.

Refer to the Customizing OpenAPI user interfaces guide for more info and examples.

UI name	Ignore specific request fields
Source code name	advanced.ignore_request_fields
Required?	No

# OAuth2 authorization URL

URL that Workato redirects you to when you select the ‘Connect’ button. This usually brings you to the login screen of your app.

This should be publicly available from the API documentation of the app you’re connecting to, under the Authentication section.

UI name	OAuth2 authorization URL
Source code name	authorization_url
Required?	Yes, when Authentication method is set to `oauth2_client_credentials` or `oauth2_authorization_code` or `oauth2_resource_owner_password`.

# OAuth2 token URL

URL that Workato will retrieve an auth token from. This auth token is used to verify that we have permission to access your app and its data.

This should be publicly available from the API documentation of the app you’re connecting to, under the Authentication section.

UI name	OAuth2 token URL
Source code name	token_url
Required?	Yes, when Authentication method is set to `oauth2_client_credentials` or `oauth2_authorization_code` or `oauth2_resource_owner_password`.

# OAuth2 token request mode

Send client ID and secret in token request body or as a base64 encoded string in the header.

UI name	How does the API require credentials to be sent to request a token?
Source code name	access_token_request_mode
Required?	Yes, when Authentication method is set to `oauth2_client_credentials` or `oauth2_authorization_code`.

# OAuth2 client ID

Public ID of the OAuth app that should be tied to Workato.

This is usually found in the Settings or Integrations page (or equivalent) of your logged in app account that you wish to connect to and should be kept secret.

UI name	Client ID
Source code name	client_id
Required?	Yes, when Authentication method is set to `oauth2_client_credentials` or `oauth2_authorization_code` or `oauth2_resource_owner_password`.

# OAuth2 client secret

Matching private key that the application will verify along with the Client ID.

This is usually found in the Settings or Integrations page (or equivalent) of your logged in app account that you wish to connect to and should be kept secret.

UI name	Client Secret
Source code name	client_secret
Required?	Yes, when Authentication method is set to `oauth2_client_credentials` or `oauth2_authorization_code` or `oauth2_resource_owner_password`.

# OAuth2 user

The name of the application user/account.

UI name	Username
Source code name	username
Required?	Yes, when Authentication method is set to `oauth2_resource_owner_password`.

# OAuth2 password

The password of the user. An alternative to your password would be an API key or API token, retrieved from your account settings.

UI name	Password
Source code name	username
Required?	Yes, when Authentication method is set to `oauth2_resource_owner_password`.

# OAuth2 scopes

Scopes are permissions that you can request from the app.

This is usually found in the Settings or Integrations page (or equivalent) of your logged in app account that you wish to connect to.

UI name	Scopes
Source code name	scopes
Required?	Yes, when Authentication method is set to `oauth2_client_credentials` or `oauth2_authorization_code` or `oauth2_resource_owner_password`.

# Object hint

Defines the field in the OpenAPI document the connector should use to display object hints.

The default implementation allows the user to select between the summary and description fields.

Consider the following object from a sample OpenAPI document:

If summary, Update an existing pet would be used as the object hint
If description, Update an existing pet by Id would be used as the object hint

{
   "paths":{
      "/pet":{
         "put":{
            "tags":[
               "pet"
            ],
            "summary":"Update an existing pet",
            "description":"Update an existing pet by Id",
            "operationId":"updatePet",
            "requestBody":{
               "description":"Update an existent pet in the store",
               "content":{ ... },
               "required":true
            }
         }
      }
   }
}

Refer to the Customizing OpenAPI user interfaces guide for more info and examples.

UI name	Object hint
Source code name	advanced.object_hint_field
Required?	No

# Object hint substitutions

Defines a list of substitutions for object hints. Useful for modifying object hint field values and improving the object picker user experience.

Substitution objects include the following properties:

pattern: A regular expression string, optionally including capture groups.
replacement: The string value to replace all occurrences of pattern. This value may contain back-references to the pattern's capture groups of:
- The form \d, where d is a group number. For example: \1
- Or \k, where n is a group name. For example: \object
If a double-quoted string, both back-references must be preceded by an additional backslash (\). Note: Special match variables such as $& won't refer to the current match within the replacement.

Refer to the Customizing OpenAPI interfaces guide for more info and examples.

UI name	Object hint substitutions
Source code name	advanced.object_hint_substitutions
Required?	No

# Object name

Defines the field in the OpenAPI document the connector should use to display object names.

The default implementation allows the user to select between the summary and operation_id fields.

Consider the following object from a sample OpenAPI document:

If summary, Update an existing pet would be used as the object name
If operation_id, updatePet would be used as the object name

{
   "paths":{
      "/pet":{
         "put":{
            "tags":[
               "pet"
            ],
            "summary":"Update an existing pet",
            "description":"Update an existing pet by Id",
            "operationId":"updatePet",
            "requestBody":{
               "description":"Update an existent pet in the store",
               "content":{ ... },
               "required":true
            }
         }
      }
   }
}

Refer to the Customizing OpenAPI user interfaces guide for more info and examples.

UI name	Object name field
Source code name	advanced.object_label_field
Required?	No

# Object name substitutions

Defines a list of substitutions for object names. Useful for modifying object name values and improving the object picker user experience.

Substitution objects include the following properties:

pattern: A regular expression string, optionally including capture groups.
replacement: The string value to replace all occurrences of pattern. This value may contain back-references to the pattern's capture groups of:
- The form \d, where d is a group number. For example: \1
- Or \k, where n is a group name. For example: \object
If a double-quoted string, both back-references must be preceded by an additional backslash (\). Note: Special match variables such as $& won't refer to the current match within the replacement.

Refer to the Customizing OpenAPI interfaces guide for more info and examples.

UI name	Object name substitutions
Source code name	advanced.object_name_substitutions
Required?	No

# Substitutions for grouping

Defines text-based substitution rules for endpoint grouping operations. This is useful when the built-in grouping rules do not meet the specific needs of your API structure.

Refer to the Customizing OpenAPI user interfaces guide for more info and examples.

UI name	Substitutions for endpoint grouping
Source code name	advanced.substitutions_for_grouping
Required?	No

# Operation name field

Defines the field to use for operation names in the picklist of the Execute API operation action. Defaults to object name field.

UI name	Operation name field
Source code name	advanced.execute_operation_label_field
Required?	No

# Query param authorization

A list of query parameters to be added to the API requests.

Examples:
api_key: 1234567890 token: abc123

UI name	Query param authorization
Source code name	query_params
Required?	Yes, when Authentication method is set to `query`

# Record ID field name

Defines the name of the field that holds an object's unique ID value.

UI name	Record ID field name
Source code name	advanced.record_id_field_name
Required?	No

# Static object names

Defines the a list of user-friendly names for objects and operations.

Refer to the Customizing OpenAPI user interfaces guide for more info and examples.

UI name	Static object names
Source code name	advanced.object_label_map
Required?	Only required if the OpenAPI document doesn't provide user-friendly names for individual API endpoints.

# Sample

{
  ...
  "advanced" => {
    "object_label_map" => [
      { 
        "operation_id" => "createPet", 
        "label" => "Create a new Pet"
      },
      ...
    ]
  }
  ...
}

Object_label_map syntax

You can format the object_label_map in the following ways:

Provide an array of objects with operation_id and label. The example shown uses this syntax.
Provide an object with keys (for operation IDs) and values (display names/labels).

# Server URL

THIS IS A REQUIRED FIELD.

A URL to the target host or service. Relative endpoint paths from the OpenAPI document will be appended to this URL to construct a full endpoint URL.

Note: If you want to hard-code this field's value - meaning end-users won't need to provide a value when setting up the connector - you'll need to provide the field in two methods:

adjust_connection:

methods: {
    adjust_connection: lambda do |connection|
      connection.merge(
        {
          'definition_mode' => 'url',
          'definition_url' => 'http://calendly.github.io/redoc/openapi.yaml',
          'base_url' => 'https://petstore.swagger.io/v2/',
          'documentation_href' => 'http://redocly.github.io/redoc'
        }
      )
    end
  [ ... ]
}

base_uri:

base_uri: lambda do |connection|
  'https://petstore.swagger.io/v2/'
end

UI name	Server URL
Source code name	base_url
Required?	Yes

# Test request URL

The relative path of an API endpoint the connector will use to test the connection.

UI name	Test endpoint path
Source code name	advanced.test_endpoint
Required?	No

# Use HTTP method semantics for grouping

Indicates if HTTP methods should be used for grouping API operations.

This should be enabled unless the endpoints in a Swagger file don't follow REST guidelines (opens new window).

UI name	Use HTTP method semantics for grouping operations
Source code name	advanced.use_operation_names_for_grouping
Required?	No

Last updated: 11/15/2023, 7:02:16 PM