Changed in 51.0.6.0 Connectors and functions

To create integrations for the SOAR Platform application with little or no coding, you can build connector functions by creating your own or by importing OpenAPI spec 3.0 files.

A function is a playbook component that sends data to a remote function processor through a message destination or REST API endpoint via a HTTP or HTTPs request.

AppExchange functions
AppExchange functions start remote code, which completes an action and then returns the results to the playbook. App functions come from the installation of a SOAR app from the IBM AppExchange or customer-written apps. You can access app functions from the AppExchange tab from the playbook function library menu for a specific playbook.
Connector functions
A connector is a collection of functions that are custom-created in SOAR or imported from the OpenAPI specification of a vendor into the SOAR Platform. Connector functions invoke the Rest API endpoint via a HTTPs request and return the results to the playbook. You can access connector functions from the Connectors tab on the main Playbook page, or from the playbook function library menu for a specific playbook.

You can use both connector functions and AppExchange functions together in a playbook, as they are complementary. You can use the connector feature to quickly add functions to your playbooks through the OpenAPI spec import and further enhance playbooks that use AppExchange functions.

To use both app and connector functions, you must deploy an App Host on which to run them.

New in 51.0.6.0 Creating custom connector functions for playbooks

You can create custom connectors in the SOAR application to build integrations for SOAR, with little or no coding required.

Before you begin

Create connectors based on the vendor provided REST API documentation.

About this task

Connectors provide a simple way to add functions to the SOAR Platform. Using connectors, you can quickly build integrations, with little or minimal coding required.

From the Connectors tab or Playbook canvas, you can create connectors and connector functions to design and run playbooks.

Important: Exporting or importing playbooks with connector functions is not supported currently and connector functions do not work in MSSP organizations.

Procedure

  1. To create a custom connector, complete one of the following actions:
    • From the Playbooks > Connectors tab, click Add connector functions > Create connector.
    • From a playbook canvas, click the Functions icon () in the playbook library, click the Connectors tab, and then click Add connector functions > Create connector.
  2. From the Connector Details section, enter the connector name in the Folder Name field and enter a description.
  3. From the Security section, click Configure to create a security profile for the function to authenticate against the REST API endpoints. If you do not configure a security profile, a half blue circle icon is displayed for the connector. Complete the following steps to configure authentication:
    1. From the Security scheme menu, select an authentication scheme. The supported authentication schemes are API Key, basic authentication, bearer, OAuth 2.0 and None. Depending on the Security scheme you select, other configuration fields are displayed.
    2. Complete any fields that appear for the security scheme that you selected. All fields that are displayed are required fields.
    3. Enter the Server URL. Server URLs must be fully qualified, including the schema, for example http:// or https://, and cannot contain variables.
    4. Enter relevant security credentials such as API key value, username and password.
    5. Save your changes.

    A green icon is shown for the connector to indicate that it is correctly configured.

    Note: If you subsequently change the security configuration, values you entered for the username and password, and other values such as client ID, client secret do not persist, so you must reenter them.
  4. From the Functions section, click Create function and provide the function details, request parameters, request body, and response for the API endpoint. Note the following:
    • Response schema definition and response sample are optional. If no schema definition is specified, SOAR saves the response based on the endpoint return result. However, function result output properties are not shown in the playbook data navigator, but it shows as "object".
    • Make sure Request body or Response parameter schema definitions do not include $ref, oneof, anyOf and allOf elements.
  5. From the Runtime section, associate the connector with a running App Host.
  6. From the Additional settings section, configure how the connector interacts with the API and handles requests.
  7. Click Save to save and return to the Connectors tab and the newly created connector is added to the connectors list.

Changed in 51.0.6.0 Creating connector functions by importing OpenAPI 3.x spec files

You can create connector functions by importing OpenAPI spec files to build integrations for the SOAR application, with little or no coding required.

Before you begin

To successfully create connectors and connector functions using the OpenAPI 3.x specification in SOAR, ensure your system meets all of the required described here.

If you try to import OpenAPI spec files that do not meet the following requirements, the import fails:

  1. Make sure there are no external references that point to external documents.
  2. Make sure that a schema is provided for path parameters, such as header and query parameters.
  3. Server parameters must be fully defined.
  4. Server URLs must be fully qualified, including the schema, for example http:// or https://, and cannot contain variables.
  5. Request parameters cannot specify media types, such as application or .json.
  6. Security schemes are limited to Basic, API key, bearer and OAuth2.0 flow grant types. Password, client Credentials and extend x-apikey .OAuth2.0 Implicit flow security scheme is not supported.

Additionally, some functions in successfully imported OpenAPI spec files will be disabled if the function definition contains one or more of following items. Correct these problems outside of SOAR and retry the import:

  • HEAD HTTP operation.
  • oneOf and anyOf schema types.
  • Request body with media types other than application or .json.
  • Missing path parameters.
You must have an OpenAPI spec 3.0 .yaml or .json file available on the system that contains the functions that you want to import. Before importing into the SOAR Platform, you can view and edit the OpenAPI spec using the swagger editor at https://editor.swagger.io.

About this task

Connectors provide a simple way to add functions to the SOAR Platform. Using connectors, you can quickly build integrations, with little or minimal coding required.

From the Connectors tab, you can import Open API spec files, parse the data, and then create connector functions to use in your playbooks. You must configure security credentials for the function to authenticate against the REST API endpoints.

Important: Exporting or importing playbooks with connector functions is not supported currently and connector functions do not work in MSSP organizations.

Procedure

  1. To start adding a connector, complete one of the following actions:
    • From the Playbooks > Connectors tab, click Add connector functions > Import connector APIs.
    • From a playbook canvas, click the Functions icon () in the playbook library, click the Connectors tab, and then click Add connector functions > Import connector APIs.
  2. From the Import connector page, click in the Upload file area.
  3. Search for and select a .yaml or .json file that contains the functions.
  4. Click Upload and then Next.
    The system parses the data in the file and renders the data onscreen.
  5. From the Connector Details page, enter a folder name for the data in the file and enter a description.
  6. From the Functions section, select the functions that you want to import. By default, all of the functions are selected. To omit any function, deselect it.
  7. From the authentication section, click Configure to create a security profile for the function to authenticate against the REST API endpoints. If you do not configure a security profile, a half blue circle icon is displayed for the connector. Complete the following steps to configure authentication:
    1. From the Security scheme menu, select an authentication scheme. The supported authentication schemes are limited to security schemes specified in the OpenAPI spec. Depending on the Security scheme that you select, other configuration fields are displayed.
    2. Complete any fields that appear for the security scheme that you selected. All fields that are displayed are required fields.
    3. From the Server URL menu, select the URL for which the function needs to authenticate.
    4. Enter relevant security credentials such as API Key value, and username and password.
    5. Save your changes.
    A green icon is shown for the connector to indicate that it is correctly configured.
    Note: If you subsequently change the security configuration, values you entered for the username and password do not persist, so you must reenter them.
  8. Click Save to save and return to the Connectors tab, where the newly created connector is added to the list of connectors.
    Remember: If your OpenAPI specs do not meet the requirements described above, you see error messages when you save the new connector. Review the error messages and correct the problems outside of SOAR and retry the import.
  9. Click the edit icon to edit the function.
    From the Edit Function page, edit the function details, request parameters, and response data as required.

Changed in 51.0.6.0 Editing a connector

You can edit a connector that you previously created. You cannot edit connectors that were created by importing OpenAPI specs.

About this task

When you edit a connector, you cannot import new functions, but you can select functions not previously selected and you can remove functions.

Procedure

  1. From the Playbooks > Connectors tab, click the connector that you want to edit.
  2. From the Edit connector page, you can make the following changes:
    Connector details and description
    You can change the connector folder name where the imported function is stored and you can change the description.
    Security section
    You configure or change the security profile.
    Note: You cannot change the security scheme for imported OpenAPI specs.
    Functions
    You can add any functions that you imported previously that are not currently selected, and you can remove functions. You cannot import new functions.
    Runtime
    Associate the connector with a running App Host.
    Additional settings
    Configure how the connector interacts with the API and handles requests.
  3. Save your changes.

Deleting a connector

You can easily delete a connector from the Playbooks > Connectors tab.

Procedure

  1. Go to the Playbooks > Connectors tab.
  2. For the connector that you want to delete, click the overflow menu () and then Delete.
  3. Click Delete to confirm.

Associating connectors with an App Host

You must use connectors with an App Host and configure the connector to use the App Host.

Before you begin

The App Host must be paired and running. If the App Host is down or you need to troubleshoot, refer to the App Host deployment guide and Troubleshooting App Host problems.

About this task

You can associate multiple connectors with the same App Host but a connector can be associated with only one App Host at a time. You can switch a connector between multiple App Hosts. If the primary App Host is down, you can switch to a secondary App Host. For example, if you have three connectors, one connector can be deployed to App Host A and connectors two and three can be deployed to different App Hosts.

Configure the App Host to use with connectors from the Playbooks > Connectors tab.

Procedure

  1. Go to the Playbooks > Connectors tab.
  2. Click the connector that you want to configure with the App Host.
  3. From the Runtime section, select an active App Host and save.

Adding functions to playbooks

You can access functions in the library from the Functions > Connectors or Functions > AppExchange tab on the Playbook canvas window.

About this task

If you are adding a connector function that you imported, go the Connectors tab, and search for and select the function.

If you are adding a function from an app, go to the AppExchange tab, where the library categorizes the functions by the app that installed them. Functions that are not associated with an app are grouped in the Other category. If you need to install a new app, click Install new app to open the Apps tab on the Administrator Settings page. For more information, see Managing SOAR apps.

To add a function to a playbook, complete the following steps.

Procedure

  1. In the Playbook canvas window, click the Functions icon () in the playbook library.
  2. Complete one of the following, depending on whether you want to add a connector function or a function from an app or other function:
    • To add a connector function, from the Connector tab, search for and select the function.
    • To add a function from an app or a function that you created, click the AppExchange tab and expand the app name to see its functions. To see functions that are not associated with an app, expand the Other category.
    Tip: Click the Open filters icon to filter the list of functions.
  3. To view information about the function, select the function from the list.
  4. To add a function to the playbook, drag it to the canvas, or click the + icon.
  5. On the canvas, select the function to open the function configuration window.
  6. Under Function output, type a name in the Output name field.

    You can use to this name to make the function output available to scripts that start later in the playbook.

  7. For the functions inputs, determine the method for delivering inputs:
    For connector functions, to define inputs, expand the Request parameters section, and select the Form or Raw tab. Use the Raw tab to use a script to enter function inputs using playbook data.
    • If you select the Form tab, enter values for each field. To select the input field directly from the playbook schema, click the Choose from schema icon ( ), and browse through the list to find the object that you want to use. Click the + icon to add the path to the input field. The object or property type must match the input field type. If it does not, a validation message appears under the input field.

    • Use the Raw tab to set a JSON payload as function Request body.
    If you want to use the connector function result outputs in the local scripts, you can use the following syntax:
    JSON Primitive types – String, Integer, Boolean, Number*
           o <fn outputname>.data
    
    incident.properties.cust_str_field = playbook.functions.results.out1.data incident.properties.boolean_field = playbook.functions.results.out1.data JSON Primitive type array
          o <fn outputname>.data[]
    
    incident.properties.cust_str_field = playbook.functions.results.out1.data[0]
    JSON Object with no root name
         o <fn outputname>.firstName
    
    incident.properties.cust_str_field = playbook.functions.results.out1.data.first_name
    JSON Object array
        o. <fn outputname>.data[0][“firstName”]
    
    incident.properties.cust_str_field = playbook.functions.results.out1.data[0][“first_name”]
    JSON Object with root name
    
    incident.properties.cust_str_field = playbook.functions.results.out1.employee[0][“first_name”]
    
    *Number can return the double/float values. However, field def support only integer values. It should be saved as string value
    
    For non-connector functions:
    • To manually define the inputs, click the Fields tab and type a value in each input field.

      To select the input field directly from the playbook schema, click the Choose from schema icon ( ), and browse through the list to find the object that you want to use. Click the + icon to add the path to the input field.

      The object or property type must match the input field type. If it does not, a validation message appears under the input field.

    • To use a script to programmatically define the inputs, click the Script tab.

      If a script is present, click Edit script to update it.

      To add objects directly from the playbook schema, click the View playbook schema icon ( ), and browse through the list to find the object that you want to use. Click the + icon to add the path to the script builder.

      For information about building scripts, see Input scripts.

  8. To duplicate or remove the function, on the playbook canvas, right-click on the function and select Duplicate mode or Remove.

Downloading connector log files

You can download connector log files to help troubleshooting or identify any problems.

Procedure

  1. Go to the Playbooks > Connectors tab.
  2. Click the overflow menu () and then Download logs.
  3. From the Download logs modal, select a time range for the logs that you want to download, either for all time available, or for a specific time range.
  4. From the Advanced settings section, you can change the log source from the current container to a previous container, if available.
  5. Click Download logs to download.