Customizing User Interfaces For OpenAPI Connectors

In addition to universal connectivity, the OpenAPI connector also allows you to customize its user interface in Workato for the best user experience.

In this guide, we'll show you how to:

1. Customize object names and hints
2. Customize how API operations are grouped into actions
3. Hide action input fields
4. Customize the connector's application name

---

Best Practices

When customizing the user interface of an OpenAPI connector, we recommend following these best practices:

1

Verify object hints are present and accurate. Ensuring information is easy to access and understand will help your users get up and running quickly.

If you have the ability to directly edit your Swagger file, add object hints and external links if needed.

2

If building a custom connector, replace OpenAPI with your application's name.

3

Test, test, test! Whether you're developing a custom connector or customizing the interface for a standard OpenAPI connector, make sure to iteratively test your changes. Identifying an issue is easier if you test one change at a time.

---

Customizing Objects

Details about objects are automatically extracted from endpoint fields. In this section, we'll cover:

• Choosing the object name field
• Customizing object hints and links
• Substitution rules for object names and hints
• Using Static object names to map user-friendly display names for objects and operations

Example endpoint

The examples in this article will use the following endpoint:

/*  swagger-petstore-1-1.json */

{
   "paths":{
      "/pet":{
         "post":{
            "tags":[
               "pet"
            ],
            "summary":"Create a new pet",
            "description":"Add a new pet to the store. [More information](https://app.swaggerhub.com/apis/Colon-Org/Swagger-PetStore-3.0/1.1)",
            "operationId":"createPet",
            "requestBody":{
               "description":"Add a new pet to the store",
               "content":{ ... },
               "required":true
            }
         }
      }
   }
}

Customizing Object Names

Object names refer to the types of records an API interacts with, such as pet or user. In the Recipe Editor, users can select the type of object an action interacts with:

Picklist of which object to operate on

Objects names are derived from the object's summary, description, or operationId field. When setting up the connection, users are prompted to select one of these options in the Object name field.

Connection setup: Select the object name field

If summary is chosen, the object name will be based on "Create a new pet", (view example endpoint). After excluded words are removed (such as a or and), the resulting object name will be Pet.

Note: You can hard-code the object name field if developing a custom connector. Refer to the Using The OpenAPI Connector To Create Custom Connectors guide for more info.

However, we recommend directly editing the Swagger file instead.

Customizing Object Hints And Links

Object hints are short, helpful descriptions that display below the object picker field:

Object hints

Users can use an object's summary or description field as the object name by default. When setting up the connection, users are prompted to select one of these options in the Object hint field.

If description is chosen, the object hint will be "Add a new pet to the store. More information (opens new window)", (view example endpoint).

Using relative path

External links in the bbject field hints be formatted two ways:

• Standard links, which contains the full URL and is typically formatted as [link text](url). For example: [Workato](https://www.workato.com). These types of links are rendered as-is and don't require any configuration.
• Categorized relative links, formatted as [link text](key:path). The key references a base URL that, when combined with the path, creates a full URL. For example:
  • Base URL: https://docs.swagger-store.io/docs/
  • Path: pets/statuses
  • Full URL: https://docs.swagger-store.io/docs/pets/statuses

Adding a Base URL

In the following example, setup the key of "doc":

/*  swagger-petstore-1-1.json */

{ 
  ...
  "description":"Multiple status values can be provided with comma separated strings. See [documentation](doc:pets/statuses) for all possible statuses."
  ...
}

You will need to supply the base URL (https://docs.swagger-store.io/docs/) to complete the helplink.

Configure the External documentation links connection fields in Workato:

Connection setup: External documentation links

Note: You can hard-code the object hint field if developing a custom connector. Refer to the Using the OpenAPI connector to create custom connectors guide for more info.

However, we recommend directly editing the Swagger file instead.

Using Substitution Rules

In some cases, removing filler words and keywords from object names and hints doesn't lead to the best results.

Let's say we're working with object names and want to use the summary field for extraction. The object's summary is "Allows users to create a pet".

If only filler words and keywords are removed, the result will be Allows users to pet - definitely not an ideal result.

You can modify extracted values before keywords and filler words are removed using the Object name substitutions and Object hint substitutions fields.

The table below demonstrates how a substitution rule that strips Allows users to from Allows users to create a pet would improve the final result:

Description		Value
Input	Value is extracted from the object's summary field	Allows users to create a pet
Pattern	Uses capture group to extract characters after Allows users to	Allows users to (.+)
Replacement	Replaces value with results of first capture group ( (.+) )	\1
Substitution result	Value after applying the substitution rule	Create a pet
Final result	Final object name after removing filler words (a, the, etc.) and known words (ex: Create) from Substitution result	Pet

NOTE

When multiple substitution rules are present:

• Workato applies the rules in the order they are present
• The value is replaced for every matching pattern
• Subsequent rules use the previous rule's result

Additionally, some hints contain relative links to external sites.

Static Object Names

If the OpenAPI spec does not provide user-friendly names for individual API endpoints, use Status object names to map descriptive display names for eat object and operation.

To remap the operation in the example endpoint, we will provide a display name for the "Create a new Pet" ("operationID": "createPet").

Connection setup: Adding a static object name

---

Customizing API Operation Grouping

• Understanding API operation assignment
• Default API operation grouping rules
• Substitution rules for API operations

Understanding API Operation Assignment

The OpenAPI connector contains a set of default rules for grouping API operations into recipe actions. These rules also control the objects displayed in the object picker when setting up an action.

The following image demonstrates how two API operations from a Swagger file would map to actions in the Recipe Editor:

MISSING SOME API OPERATIONS?

If an action doesn't contain an API operation you expect it to, look for it in the Execute operation action.

If an API operation can't be matched, the connector will group the operation under this 'fallback' action. Refer to the Default operation grouping rules section below for more info.

Grouping rules are based on two factors:

• Keywords in the API operation's summary and operation ID. When the connector parses the Swagger file to create recipe actions, it's also checking for keywords in the API operation's summary and operationId fields. The connector uses these keywords to assign operations to recipe actions.

  For example, an operation ID of createPet would assign the operation to the Create record action. This is because the operation ID contains the word create.

• The operation's HTTP method, which is specified in the Swagger file. HTTP methods describe the type of action an operation performs for a given object, such as create (usually POST) or search (GET).

  For example, operations that use the GET method would be assigned to either the Search records or Get record details by ID action.

  To disable this grouping method, set the Use HTTP method semantics for grouping operations field to No when setting up the connection. This can be useful if an API doesn't follow REST standards. For example, every endpoint uses the POST method.

Default API Operation Grouping Rules

The following table details the default operation grouping rules for OpenAPI connectors. The table columns are as follows:

• Name and description: The name and description of the action

• Operation keywords: The keyword(s) the connector uses to perform API operation grouping. If an API operation's summary or operationId contains these keywords, it will be mapped to this action in the Recipe Editor.

  For example: If a summary or operationId contains add or adds, the API operation will be assigned to the Create record action.

• HTTP methods: If the Use HTTP method semantics for grouping operations option is enabled, the connector will match the methods list to this action.

  For example: If an operation uses the POST method, it will be assigned to the Create record and Update record actions.

Name and description	Operation keywords	HTTP methods
Create record Creates a new record of a specified object type. For example, if a pet object is selected, this action will create a new pet record.	create, creates update, updates post, posts add, adds upload, uploads new	POST, PUT
Update record Updates an existing record using its unique identifier.	create, creates update, updates put, puts set, sets upload, uploads modify, modifies manipulate, manipulates	PUT, POST, PATCH
Search records Searches for records of a specified object type.	return, returns find, finds list, lists (all) search, searches retrieves objects/records/all get(s) (a) collection (of) get list (of)	GET
Get record details by ID Retrieves a record using its unique identifier.	get, gets return, returns find, finds show, shows retrieve, retrieves single download, downloads getSingle get-single	GET
Delete record	delete, deletes remove, removes kill, kills	DELETE
Execute operation This action is considered a 'fallback'. If an API operation can't be matched to a specific action, it will be grouped under this action.		POST, PUT, GET, DELETE, PATCH

Substitution Rules For API Operations

If operation IDs in your Swagger file aren't as simple as createPet or searchPets, you can use substitution rules to improve or customize API operation grouping.

The table below demonstrates how a substitution rule transforms an operation ID of operation-8452/pet-create to create-pet:

Description		Value
Input	Value is extracted from object's operationId field	operation-8452/pet-create
Pattern	Uses capture groups to extract the object (pet) and verb (create) of the operation ID	operation-8452/(?<object>.+)-(?<verb>.+)
Replacement	Replaces value with results of the capture groups	\2-\1
Final result	Final operation ID after applying the substitution rule	create-pet

The connector can now assign the API operation to the Create record action with an improved operation ID of create-pet.

NOTE

When multiple substitution rules are present:

• Workato applies the rules in the order they are present
• The value is replaced for every matching pattern
• Subsequent rules use the previous rule's result

---

Ignoring Action Input Fields

Actions in Workato contain input fields used to configure the action. Using the Ignore specific request fields field when setting up the connection, you can specify fields to ignore. Ignored input fields are hidden from view when users set up actions.

For example, let's say an endpoint contains a links field. Using the following configuration, this field can be ignored:

Nested fields can also be ignored by providing the field path using dot notation. For example, if links had a url field you wanted to ignore, you would enter links.url as the Field name:

---

Customizing The Application Name

NOTE

This section applies only to custom OpenAPI connectors.

In the default source code, OpenAPI is used in several places. We recommend replacing this value with the name of your application when you create a custom connector.

Along with changing the application name, you can change other text elements to improve the user experience. For example, changing via to in.

Let's look at an example using the create_record action. In this case, OpenAPI is used in the action's subtitle:

create_record: {
  title: 'Create record',
  subtitle: 'Create record via OpenAPI',
  description: lambda do |_input, picklist_label|
    record = picklist_label['object_for_create'] || 'record'
    "Create <span class='provider'>#{record}</span> " \
      'via <span class="provider">OpenAPI</span>'
  end,
  [...]

Then in the recipe editor, the action will display like this:

Along with action subtitles, changing the application name to that of your application can affect several elements in the recipe editor, including:

• Object field hints:

  

• Recipe action descriptions:

  

To simplify replacing OpenAPI with your application's name, perform a case-sensitive find/replace in the source code. Note: To perform this action, you may need to use a text editor like Sublime Text.