Custom Node Integration

Custom Node Integration feature allows you to configure reusable integrations with your existing business system or with third-party applications using REST/SOAP APIs. Once a custom node is configured, it becomes available for use across various flows within your Team/Group/Across Platform. For more information on accessibility of Custom Node within your Team/Group, please refer to Groups and Teams.

It can also be used over HTTP Request Node, when you want to configure a reusable integration node, or when you need to integrate with an API that supports advanced authentication mechanisms that are not supported within HTTP Request node.

You must have the following resources for building a custom node integration:

• REST API: a resource URL that points to the location of the third-party APIs.
• SOAP API: a WSDL file or its location. A WSDL file contains a set of web services, their methods, and functionality.

📘

Custom Node integration is an add-on feature available as part of some select Webex Connect tiers. Please get in touch with your account manager if you would like to enable it for your tenant.

Callback URLs for all your pre-built integrations, custom integration configurations, that use OAuth 2.0 authorization with ‘Auth Code’ Grant Type will be updated with Webex Connect branded URLs. This doesn’t impact functioning of any of your existing integration configurations until the Refresh Token for that integration expires or until you decide to reauthorize. In either of these two cases, you would need to start using the new Callback URL provided on Webex Connect UI in the third-party application you have integrated with. Another example of this is OAuth 2.0 based authentication for Gmail when using SMTP for Outbound Email channel configuration which is currently available only for Webex Connect tenants used for Webex Contact Center Integration.

Please make sure your applications, firewalls, etc. do not restrict access to these new Callback URLs in case you have an internal policy/practice to add these URLs to the allow/accept/allowed list.

Create a Custom Node

To create a custom node:

1. Click Assets > Integrations > Add Integration > Custom Node on the services dashboard.
2. Enter the following details in the Create New Custom Node dialog box:
   a. Node Name – the name of the custom node.
   b. Description – meaningful description of the custom node. This is optional.
   c. API Integration Type – the API type you want to use for the custom node integration.
   d. Node Category – the category under which you want to classify the custom node. You can either choose an existing category or create a new category.
   e. Creation Type – choose to create a blank integration and configure it or copy the configuration from an existing integration.
   f. Node Icon – select an SVG file that you want to use as an icon for the custom node. This is optional.
3. Click OK to create a custom node with the provided details.

Configure a REST API Node

Specify the resource URL for the RESTful API, create methods, and configure the methods.

1. Configure the request details of the method.
2. Configure the interface of the node.
   After you configure this node, you can use it in the flows like any other node.

Configure Request Details

On the Settings tab, you can add methods and configure the method settings.

To add a method:

1. Provide the Request Details.
   a. Request Name – the name of the request or the method.
   b. Request Timeout (ms) – duration (in milliseconds) after which the request times out.
   c. Connection Timeout (ms) – duration (in milliseconds) after which the connection times out.
   d. Type – method type of the request. Any REST API supports the POST, PUT, GET, DELETE, and PATCH method types.
   e. Resource URL – the location where the third-party service provider hosts the REST API. Use the notation of $() if you want to pass variables in the URL. For example, $(param1).
   f. Parse Variables – button to parse the variables in the URL and extract them.

📘

Restriction on number of methods

From v5.6.0 release onwards, you can add only up to 25 methods in a Custom Node. Existing custom nodes will not be affected by this change; however, you will not be able to add additional new methods to a custom node already using 25 or more methods.

2. Select an Authorization type and configure the details. This is optional.

👍

Authorization Types Supported by Custom Integration Node

• Basic Auth
• Digest Auth
• AWS Signature
• OAuth 2.0

You must configure the following parameters based on the authorization type:

a. No Auth – select this type when you do not need an authorization
b. Basic Auth – select this type when you need to do an authorization using username and password

c. Digest Auth - select this option when you need to validate the user identity before sending any sensitive information like online banking transactional details. In this type of authorization, a network server receives the request from a user and then sends it to a domain controller. The domain controller responds with a special session key.

d. AWS Signature - select this option when you want to use the Amazon Work Services workflow for authorization. You must use a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication.

e. OAuth 2.0 – is a well-adopted delegated authorization framework. Webex Connect custom node supports two different grant types for OAuth 2.0

1. Authorization code - server issues the token in the context of a user.
2. Client credentials - grant type is used to obtain an access token outside of the context of a user.

3. Enable Security Configuration, if required. This is optional.
   When you enable it, you can configure the security certificate(s).
   a. Configure Key Store Certificates.
   Click Add New and configure the following fields:

Based on the expiry date (Valid Till date), an email is sent to the owner, full-access, and limited-access users of the tenant to remind you 30, 15, 7, 3, 2, and 1 day(s) before expiry. If you do not upload a valid certificate after the expiry date, another email is sent 1 and 7 days after expiry.

b. Configure Trust Store Certificates.
Click Add New and configure the following fields:

Based on the expiry date (Valid Till date), an email is sent to the owner, full-access, and limited-access users of the tenant to remind you 30, 15, 7, 3, 2, and 1 day(s) before expiry. If you do not upload a valid certificate after the expiry date, another email is sent 1 and 7 days after expiry.

c. Configure Security Protocols.
Select the security protocol that applies to the security certificate. You can select multiple protocols for a single certificate. Webex Connect supports two categories of protocols:
• SSL (Secure Sockets Layer) - standard security protocol that establishes a secured and encrypted connection between a web server and a browser
• TSL (Transport Layer Security) - security protocol that provides privacy and data integration between two communicating applications.

📘

Note

SSL 2.0 and 3.0 are not supported for new custom node tenant configurations, but will work as is for the existing tenants.

4. Specify Header parameters. This is optional.
   Click Add New and add the parameters that you want to send in the header of the request.
   Define the following fields:

5. Define URL Parameters. This is optional.
   Click Add New to add parameters that you want to send in the URL of the request. Provide details for the following fields:

6. Configure Body of the request.
   The request body can be in any of the following formats:
   • Text (text/plain)
   • JSON (application/json)
   • XML (application/xml)
   • form-data
     Select a suitable format and enter or paste the body. You can directly add parameters to the body using the Add Parameters button. The Parse button allows you to extract the parameters from the body of the request.
     Specify the following details and configure the parameters:

7. Configure the Response of the request.
   Import response paths from a sample response to create a node event. A node event signifies the outcome of a node. Specify the status code/response path to create a node event and map it. You can map multiple responses to a node event.
   You can save the response path and use it as a variable within the node.
   1. Select a suitable format for the response. The response can be in Text (text/plain), JSON (application/json), or XML (application/xml) formats. You can import a sample response for JSON or XML.
   2. Click Parse when you import the response from a sample to populate both node events and node variables with the response path. Select the required parameters and click Import to complete importing the response.
   3. Fill in the required details and Configure Node Events.
   4. Set data to be returned in a flow session.
      The parameters you add here appear as output variables in the node. You can map these parameters to session variables in the node.
      Click Add New and provide the following details for the parameters and repeat the steps for all parameters you want to add.
      • Parameter Name
      • Body – Body, HTTP Status, or HTTP Header
      • Response Path – specify a response path for Body and HTTP Header. HTTP Status does not require a response path.

        📘

        Workaround for 'Text/Plain' response type.

        When you configure 'Text/plain' as the Response, the following aspects are to be additionally configured. Under 'Set data to be returned in a flow session', you configure 'Parameter Name' as 'Param', select 'Body' as the response data location, and use '$.' under 'Response Path'.

        In the Flow, you might expect to access the 'Param' variable using the format $(NodeID.Param), but this returns a null value for the variable. Instead of using $(NodeID.Param), the variable can be accessed via $(Param).

        Please note that this workaround is only applicable for the 'Text/Plain' response type."

8. Click Save to save the details of the request.
9. Use the Test button to launch the Node Configuration dialog where you can preview the configuration settings of the node.

Callback URL

The callback URL is not accessible through a web browser. You need to test it using the custom node only.

Configure the Node UI

The Node UI tab allows you to configure all the dynamic parameters in the method. You can group the parameters, make the parameters mandatory, perform regex validation, and add a tooltip to the parameter.

1. Specify the Information Text. This is optional.
   This is the description of the node and it appears on the Node Configuration dialog.
2. Add New Field Group. This is optional.
   All parameters appear under the Ungrouped category by default. Create field groups and move the parameters around to group them.
3. Select the Field Type for each parameter – Text box, Selection box, or Date and time. Text box is the default type.

4. Mark the parameter as Mandatory Parameter if it is a required parameter. It is the default selection.
5. Provide text that you want as Tooltip.
6. Click Save to save the node configuration.
7. Use the Test button to launch the Node Configuration dialog where you can preview the configuration settings of the node. You need to pass values for the dynamic parameters.

Configure a SOAP API Node

Specify a WSDL file and the methods within that file to use for the SOAP API node integration.

1. Enter the WSDL Location or browse for a WSDL file on your local machine and click Parse.
   When you browse your local machine, you must select a zip file that contains the WSDL file. Select the required WSDL file within the zip file.
2. Select the required methods within the WSDL file and click Import to import those methods into the custom node.
3. Configure the request details of the method.
4. Configure the interface of the node.
   After you configure this node, you can use it in the flows like any other node.

Throttling for Custom Node Integration

The custom node integration now provides you with the ability to configure the following throttling limits:

• Rate Limit – Limit the total number of requests per second. Beyond this limit, the node returns 429 response code.
• Concurrency Limit - Limit the maximum number of parallel custom node executions. Beyond this limit, the node returns 430 response code.
• Volume Limit - Limit the maximum number of custom node executions within a time period. Beyond this limit, the node returns 430 response code.

These limits can be used to control the rate at which the requests will be made to an API that’s being called from the respective custom node. Once enabled, these limits apply at a platform level to all the flows that use the concerned custom node and may impact the flow execution rate depending on the configurations.

Response Codes

The following are the response codes when the custom node throttle limits have reached:

• 429 - Throttle rate limit reached - Too Many requests,
• 430 - Throttleconcurrencylimit reached - Too Many requests,
• 431 - Throttlevolume limit reached - Too Many requests.

You can find the logged codes in sfe_trans_logs.

📘

Note

This integration is available only in the cloud version of Webex Connect.