Overview of the Universal Connector wizard

The Universal Connector wizard is used to create a custom module. The following sections list the fields and settings on each page of the wizard.

Step 1: Module Configuration

The Module Configuration page contains the following fields and settings:

• Name: The name of the module to identify it in Flow manager and Flow Studio. Since this name is shown with the icon, keep it short. Use only alphanumeric characters and spaces.

• Display Type list: A legacy setting that has no major impact on module functionality. The two options are Input and Output. If selecting Input, the module is assigned the Target Property setting. If selecting Output, the result of the API call is assigned to the default data property. This setting is also used in Flow Studio when filtering Input and Output module categories.

• Select File: Select a graphic in PNG format to serve as the icon that appears on the module label. The icon should be square with a resolution of at least 256 x 256 pixels, preferably 512 x 512 pixels. The icon appears on the module with the module name in CONNECT flows. A default icon is used if no pictures are uploaded.

Step 2: Version

Assign a version number in x.y.z format to the module here. If modifying an existing Universal Connector module, a higher version number must be assigned. The wizard automatically increments the middle version number; for example, changing 1.0.0 to 1.1.0. Change this number to whatever is needed as long as it is higher than the last version.

Step 3: Authentication

If an API requires authentication, read the information in this section. When a custom module is used in Flow Studio, the available credentials appear from a dropdown list. If no authentication is required, you can skip this step.

Bearer, OAuth, and Username and password authentication

If the API uses bearer, OAuth2, or basic authentication, select one of the following authentication methods from the Credential dropdown list:

• API-key: Use for bearer authentication

• OAuth Client Credential Grant: Use for one of the supported OAuth methods

• Username and Password: Use for basic authentication

Select one of these credentials to use the credentials in the central credentials store. See Credential types and examples.

Other authentication

If the API uses another authentication method, enter information into the following sections on the Authentication page:

• Authentication headers

• Authentication query parameters

Add additional header and query parameters using Add Header and Add Parameter. Any number of headers and query parameters can be added along with using parameter syntax.

Use credentials in custom authentication

Use data from credentials from the credentials store with custom authentication. Select the Use credentials in custom authentication option and then select the credential type from the Select Credential dropdown list. Then, for any parameters used in the URL, headers or query parameters can be linked to data from a credential in Step 4: HTTP Configuration.

Allow untrusted certificates

If planning to connect to a service that uses self-signed certificates, select Allow untrusted certificates to disable certificate validation.

Step 4: HTTP Configuration

This step configures the main parts of your API request. The following settings are available:

• URL: The complete URL of the endpoint, including the path.

  • Valid URL example: https://api.example.com/

  • URLs can be configured using parameters. For example, https://api.example.com/{resource}, where resource is replaced at runtime depending on how this parameter has been configured (see the next step).

  • To make the whole URL configurable, enter a parameter like {url} in this field.

• Action: The HTTP verb (action) to use. If an action where a payload body can be used, such as POST/PUT, the Body field is shown as well.

• Headers and Query parameters: Enter the required headers or query parameters into these fields and then select Add Header/Add Parameter. Multiple headers and query parameters can be added and configurable parameters can be used. See Parameter syntax for Universal Connectors.

• Body: Used for actions that require a body payload. Any text can be added here and also combined with configurable parameters. If the whole body needs to be transitioned from the incoming message, enter {body} and set the body parameter to a message parameter. Then, any data assigned to the body property on the incoming message is inserted as the body payload.

Step 5: Module settings

When incorporating this optional step, configure the required parameters for the API request in the previous step. If configurable parameters are not used, skip these steps. If the Input module type was selected in the first step, there is a default parameter called targetPropertyParameter that can be used to write the result of the API request to. This parameter's position in the module UI is the only thing that can be changed. If there are more parameters, they are marked with a red stripe to indicate additional settings need to be added. Selecting one of these parameters opens a side-panel where the information can be added. For each parameter, specify the following:

• Source: Where to get data from for this parameter. The options are User setting, Message parameter, User setting if set.

• Display name: [User settings only] The text displayed above the parameter input field in the module UI.

• Type: [User settings only] The expected data type: String, Number or Boolean.

• Requirements: [String and number user settings only] Specify the minimum and maximum lengths for strings or minimum and maximum values for numbers. These settings are optional.

• Default value: [User settings only] Default value for the parameter. A value must be entered when using the module. Empty input fields are not permitted for a Universal Connector module in a flow.

• Help text: [User settings only] Text written under the input field in the UI. Use this to help the user enter the expected data. This setting is optional.

• Purpose: [User settings only] Text used to describe the parameter in the Settings table on the Documentation tab in the module UI. See next step.

When multiple parameters are used, switch between the parameters in the side-panel by using the arrow keys. The order of the settings in the UI can be adjusted using the up and down arrows to the right of each setting. Make sure there are no red stripes on any parameters before moving on to the next step.

Step 6: Documentation

This is an optional step if to include documentation that describes the Universal Connector module. Add text in markdown on the Edit tab. The Preview tab displays how the text will appear. There are two sections for adding documentation:

• Connector description: The text that appears in a pop-up when users place their mouse pointer over a module in Flow Studio.

• Module documentation: The text that appears on the Documentation tab in the Module Settings window. It is divided into three sections:

  • Introductory text for describing what the module does.

  • Settings table: Autogenerated content based on previously added information.

  • Last section: Used to describe what input messages this module expects, what the output will look like, and, preferably, examples explaining module use cases.

Step 7: Release Notes

Release note information is added in Markdown format for the module version.

Step 8: Summary

The Summary step presents a preview of what the module will look like in the Flow Studio, including the module icon, pop-up text, settings, and documentation.