Prepare connector documentation

This is an Early Access feature for existing Workflows users. To enable it, use the Early Access Feature Manager as described in Manage Early Access and Beta features.

Every Workflows connector requires user documentation, and it must be included as part of the connector submission. The Okta Integration Network checks your documentation for general adherence to your submitted connector as part of the Okta verification process. After your connecter is published and made available in Okta Workflows, you can set the documentation link as customer accessible, publicly accessible, or limit access to users of the connector.

Such content helps customers to understand how to configure and use your connector, learn about the input and output fields of your connector's action cards, and to anticipate any performance issues that may take place when running flows that contain one or more action cards that you've built.

The documentation that you provide for your connector must explicitly state the version number of the connector to which the content applies. When a new version of your connector is released for production, your documentation set must state the new version number clearly in addition to the features updates in that new version.

The documentation site that you provide will be accessible through the Workflows in-product help pane. When a user clicks the help icon on any card or in other dialogs, a help pane appears and displays a link to the externally hosted help documentation for the connector.

User documentation for your connector can be in any format that can be hosted and accessed by Workflows users, including HTML, a Google Doc, a Microsoft Word document, or a PDF.

A documentation set for your connector must include the following assets:

  • Authorization

  • A help topic for each action card, including Custom API Action cards

  • Optionally, help topics for troubleshooting, FAQs, or other guidance for users of your connector and its cards

Topics

Authorization

An Authorization topic should include any relevant information to help a user create and reauthenticate a connection.

When users add your connector to a flow for the first time, they’ll be prompted to configure a connection. The connection will enable a user to connect to their account or environment, save their credentials, and reuse the connection when they build new flows that also include any of your connector cards.

Prerequisites

In this section, specify any prerequisites that a user must complete before configuring a connection to your connector. For example, if a user needs to generate an API Key or configure an OAuth application before they can connect to their account, then that information should be specified as prerequisites in the Authorization topic for your connector. Here's an example of a Prerequisites section:

Generate an API Token

Authentication to the Enterprise API is controlled via instance-level bearer tokens. To generate one:

  1. Log in and click Settings.

  2. Click the Access tab.

  3. Locate your instance's specific API URL.

  4. Click Add to create a new API key.

  5. Provide a Name value for your API token.

  6. Click Save. A new dialog appears that provides the API token.

  7. Click the visibility symbol to expose the API token.

  8. Click Copy to copy the API token to your clipboard.

  9. Click Close.

Set up a connection

The Authorization topic must include a set of steps that describes how users of your connector can create a connection to your service. Here's an example of a Set up section:

  1. From the Connections page or any card, click New Connection. The New Connection dialog appears.

  2. Add a string to the Connection Nickname dialog. This is useful if you plan to create multiple connections to share with your team.

  3. Paste the API token created in the Setup section into the API Token field on the dialog.

  4. Click Create.

Supported scopes

For OAuth or other token-based authentication, a list of the scopes that are required to use the connector should be included in the documentation. Include any setup details in the Prerequisites and Set up sections. Here's an example of a Supported scopes section:

  • https://www.googleapis.com/auth/userinfo.profile

  • https://www.googleapis.com/auth/userinfo.email

  • https://www.googleapis.com/auth/gmail.settings.basic

See these examples of Authorization topics:

Reference help for every connector card

Every card for a connector should be supported by a reference help topic that describes the purpose of the card, and defines the fields of the card.

Name and description

The help topic for a card should clearly indicate the name of the card and provide a brief description such as a simple imperative sentence describing the action that can be performed by the card. This information can match what was added in the name and description section of the action flow associated with the card. Other information specific to the card can be included here as well.

Definitions for fields on a card

The same help topic should also include information for every option, input, and output field on a card. For every field, the following should be provided:

  • Label: The name of the field.

  • Definition: Describe the purpose of the field, such as the data that is expected to be passed to this field as an input or output.

  • Type: Specify the type of data that is allowed for this field. For example, Number or List of Text.

  • Required: Indicate whether a value must be added to this field in order to run a flow successfully.

For options fields, all the choices in an options field must be listed in the help topic.

Groups of fields

All options, inputs, and outputs are grouped on a connector card.

For options, the group name is labeled Options and cannot be changed. For inputs and outputs, all fields must be located within one or more groups whose labels are changeable. All group labels should be included in the help topic.

Limitations and known issues

The same help topic should also include information about limitations and known issues for that card. For example, if a card may not perform optimally if it its processing a large set of records, or if a dropdown for an options field can only display a subset of all possible choices, then the help topic should clearly include such information.

See these examples of reference help topics for connector cards:

Reference help for Custom API Action cards

A Custom API Action card for your connector should also be supported by a reference help topic.

Introduce the topic with the following sentence:

Use the Custom API Action to make an authenticated custom API request to the <your service> REST API.

Options

For the Request Type field, specify the methods that your Custom API Action card supports by using these definitions as needed:

GET Retrieves data from a web server based on parameters. This method requests a representation of the specified resource. If a request is successful, a 200 (OK) response message is returned with the requested content.
POST Sends data to a web server based on parameters (for example, uploading a file). Multiple POST requests may result in a different outcome than a single POST. Caution should be exercised to avoid sending multiple POST requests unintentionally. If a request is successful, a 200 (OK) response message is returned.
PUT Sends data to be stored at a specific location on a web server based on parameters (for example, uploading a file). Unlike POST requests, PUT requests are idempotent. For successful requests, the result of a single PUT request is the same as many identical PUT requests. If a request is successful, a 200 (OK), 201 (Created), or 204 (No Content) response message is returned.
PATCH Applies partial modifications to a resource on a web server based on parameters. PATCH is not idempotent. Multiple PATCH requests could have unintended consequences. If a PATCH is successful, a 200 (OK) or 204 (No Content) response message is returned.
DELETE Deletes the specified resource (if it exists) from the web server based on parameters. If a DELETE is successful, a 200 (OK) response message is returned.

Inputs

For the input fields section, provide definitions for the following fields:

  • Relative URL

  • Headers

  • Query

  • Body

Here's an example of a definition for the Relative URL field for the Custom API Action card of the Google Calendar connector:

URL address on the web server to which you are attempting to interact. Specify the relative URL as /{version}/{insert_remaining_URL}. You can specify query parameters in the relative URL using "?", or specify the query parameters as an object key pair in the Query input.

For example, for the Google Calendar API endpoint:
https://www.googleapis.com/calendar/v3/users/{userId}/calendarList the relative URL is: /v3/users/{userId}/calendarList.

Ouputs

For the ouput fields section, provide definitions for the following fields:

  • Status Code

  • Headers

  • Body

Here's an example of a definition for the Status Code field:

Result of the operation. The HTTP status code is returned by the connector and indicates whether the action taken by the card succeeded or failed. For example:

  • A 201 Created status code indicates success where a new resource was created.

  • A 403 Forbidden error indicates that the HTTP request was not processed because the necessary permissions were missing.

For a full list of possible status codes, see HTTP status codes.

See these examples of reference help topics for Custom API Action cards: