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.

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.
FieldDescription
ParameterVariable parsed from the URL
Parameter TypeSpecify If the parameter is Static or Dynamic
Parameter ValueThis is applicable if the parameter is static. Provide value.
Field NameThis is applicable if the parameter is dynamic. Provide value at runtime.

📘

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.

  1. 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

FieldDescription
Username/PasswordLogin credentials that you want to use for authentication
Parameter Value TypeSpecify If the parameter is Static or Dynamic
Parameter valueThis is applicable if the parameter is static. Provide value.
Field NameThis is applicable if the parameter is dynamic. Provide value at runtime.

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.

FieldDescription
UsernameUsername to authenticate the request
RealmString from the server within the www-Authenticate response header
PasswordThe password to authenticate the request
NonceUnique string from the server within the www-Authenticate response header
AlgorithmString that indicates a pair of algorithms used to produce the digest and a checksum
QOPThe quality of protection applied to the message. The value must be one of the alternatives specified by the server in the www-Authenticate response header.
Nonce CountThe hexadecimal count of the number of requests (including the current request) that the client has sent with the nonce value in this request.
You must specify the count only if a QOP directive is sent in the www-Authenticate response header.
Client NonceAn opaque quoted string value provided by the client. This value is used by both client and server to avoid chosen plaintext attacks, provide mutual authentication, and message integrity protection.
You must specify the count only if a QOP directive is sent in the www-Authenticate response header.
OpaqueA string specified by the server in the www-Authenticate response header. Use this string as is with URLs in the same protection space. Webex Connect recommends that this string be base64 encoded data.

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.

FieldDescription
Access_KeyUnique access key for an account used to send the request
Secret_KeyThe unique secret key for an account used to send the request
RegionThe region that receives the request
Service_NameService that receives the request

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.
FieldDescription
Consumer IDUnique identifier of the consumer obtained during the registration process
Grant TypeType of authentication - Authorization Code or Client Credentials. Its selection depends on the grant type offered by the API.
Client ID (Client Credentials only)Unique identifier of the client obtained from the platform through which the authorization is done
Client Secret (Client Credentials only)The unique secret of the client obtained from the platform through which the authorization is done
Consumer ID (Authorization Code only)Unique identifier of the consumer obtained during the registration process
Consumer Secret (Authorization Code only)The unique secret of the consumer obtained during the registration process
Call Back URL (Authorization Code only)Webex Connect callback URL will be used during the registration process at the authorization provider’s end.
Note: The callback URL is not accessible from a web browser. You need to test it using the custom node only.
Authorization URL (Authorization Code only)Endpoint for authorization server, which retrieves the authorization code must be provided by the authorization provider.
ScopeScope of the access request (multiple space-separated values). This is optional.
Access Token URLEndpoint for the resource server, which exchanges the authorization code for an access token
Access token has a limited validitySpecifies if the token has a limited validity and must be provided by the authorization provider.
ValidityValidity of the token
Refresh URL TokenIt should be provided by the authorization provider.

It ensures smooth functioning of authorization in the case provided access token has limited validity.
Advance SettingsToggle button that allows you to enable or disable advanced settings
Access Token URL MethodAn additional method for the access token
Access Token URL Parameter typeType of access token URL parameter – Body or URL
Access Token URL HeadersAdditional URL header parameters for the access token
Get Access TokenButton to retrieve the access token
Access TokenDisplays the refresh token
Refresh TokenDisplays the refresh token
Client AuthenticationValue of Client Authentication is defined by the authorization provider’s API.

Send client credentials in body is selected by default.
ValidityThe validity of the token
  1. 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:
FieldDescription
Browse CertificateBrowse and upload the key store certificate
Select File FormatSelect the key store file format – JKS or PKCS12
Store PasswordThe password to access the store
Key PasswordThe password to access the key
NameEnter a name for the certificate
ValidateClick the button to extract the validity information from the certificate
Valid FromThe date from which the certificate is valid. This field is greyed out and automatically populated when the certificate is validated. This is a read-only field.
Valid TillThe date until which the certificate is valid. This field is greyed out and automatically populated when the certificate is validated. This is a read-only field.
IdentifierUnique identifier of the certificate. This field is greyed out and automatically populated when the certificate is validated. This is a read-only field.

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:

FieldDescription
Browser CertificateBrowse and upload the key store certificate
Select File FormatSelect the key store file format – JKS or PKCS12
Store PasswordThe password to access the store
NameEnter a name for the certificate
ValidateClick the button to extract the validity information from the certificate
Valid FromThe date from which the certificate is valid. This field is greyed out and automatically populated when the certificate is validated. This is a read-only field.
Valid TillThe date until which the certificate is valid. This field is greyed out and automatically populated when the certificate is validated. This is a read-only field.
IdentifierUnique identifier of the certificate. This field is greyed out and automatically populated when the certificate is validated. This is a read-only field.

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.

ProtocolDescription
SSL 2.0 (Deprecated)Initiates a handshake at the beginning of the connection
SSL 3.0 (Deprecated)Initiates a handshake with SHA-1 ciphers and support for certificate authentication
TLS 1.0Uses HMAC and requires DSS/DH support
TLS 1.1Uses explicit implicit initialization vector (IV) to protect against Cipher block chaining attacks
TLS 1.2Uses cipher-suite-specified pseudorandom function and is the current version of the TLS protocol

📘

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.

  1. 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:
FieldDescription
ParameterName of the parameter or variable
Parameter Value TypeType of parameter – Static or Dynamic
Parameter ValueValue of the parameter/variable
This is applicable only for a static parameter.
Field NameName of the field to which you can pass a value
This is applicable only for a dynamic parameter.
  1. 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:
FieldDescription
ParameterName of the parameter or variable
Parameter Value TypeType of parameter – Static or Dynamic
Parameter ValueValue of the parameter/variable
This is applicable only for a static parameter.
Field NameName of the field to which you can pass a value
This is applicable only for a dynamic parameter.
  1. 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:
FieldDescription
ParameterName of the parameter or variable
Parameter Value TypeType of parameter – Static or Dynamic
Parameter ValueValue of the parameter/variable
This is applicable only for a static parameter.
Field NameName of the field to which you can pass a value
This is applicable only for a dynamic parameter.
  1. 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.
a. 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.
b. 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.
c. Fill in the required details and Configure Node Events.
d. 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.
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.
FieldDescription
Text box• Regex Validation – add a regex validation string
• Test Regex- check if the regex validation string is valid
Selection box• Add New – use to add values to the selection box
• Display Name – the name of the option in the selection box
• Value – value of the option in the selection box
Date and time• Date format – format of the date
• Date-Time Separator – separator between date and time
• Time format – format of time
  1. Mark the parameter as Mandatory Parameter if it is a required parameter. It is the default selection.
  2. Provide text that you want as Tooltip.
  3. Click Save to save the node configuration.
  4. 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.

Configure Request Details

On the Settings tab, you can see the methods imported from the WSDL file. Configure the method settings.

  1. Provide the Request Details.
    a. Request Name – the name of the request as available in the WSDL.
    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. SOAP API supports only the POST method.
    e. Resource URL – location of the method as available in the WSDL. 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.
  2. Select an Authorization type and configure the details. This is optional.
    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
FieldDescription
Username/PasswordLogin credentials that you want to use for authentication
Parameter Value TypeSpecify If the parameter is Static or Dynamic
Parameter valueThis is applicable if the parameter is static. Provide value.
Field NameThis is applicable if the parameter is dynamic. Provide value at runtime.
  1. 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:
FieldDescription
Browse CertificateBrowse and upload the key store certificate
Select File FormatSelect the key store file format – JKS or PKCS12
Store PasswordThe password to access the store
Key PasswordThe password to access the key
  b. Configure Trust Store Certificates.

Click Add New and configure the following fields:

FieldDescription
Browser CertificateBrowse and upload the key store certificate
Select File FormatSelect the key store file format – JKS or PKCS12
Store PasswordThe password to access the store
  c. Configure Security Protocols.
  Select the security protocol that applies to the security certificate. You can select multiple protocols for a single certificate. <<prodname>> 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.
ProtocolDescription
SSL 2.0Initiates a handshake at the beginning of the connection
SSL 3.0Initiates a handshake with SHA-1 ciphers and support for certificate authentication
TLS 1.0Uses HMAC and requires DSS/DH support
TLS 1.1Uses explicit implicit initialization vector (IV) to protect against Cipher block chaining attacks
TLS 1.2Uses cipher-suite-specified pseudorandom function and is the current version of the TLS protocol
  1. Specify Header parameters. The header parameters defined in the WSDL appear here.
    Click Add New to add any additional parameters and define the parameter name, type and value.
  2. 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:
FieldDescription
ParameterName of the parameter or variable
Parameter Value TypeType of parameter – Static or Dynamic
Parameter ValueValue of the parameter/variable
This is applicable only for a static parameter.
Field NameName of the field to which you can pass a value
This is applicable only for a dynamic parameter.
  1. Configure Body of the request.
    The body of the request as available in the WSDL appears here in an XML format. You can add any additional 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:
FieldDescription
ParameterName of the parameter or variable
Parameter Value TypeType of parameter – Static or Dynamic
Parameter ValueValue of the parameter/variable
This is applicable only for a static parameter.
Field NameName of the field to which you can pass a value
This is applicable only for a dynamic parameter.
  1. Configure the Response to 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.
    a. Enter details like node event, body, response path, condition, value, and node edge to Configure Node Events.
    b. 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.
    c. Click Add New and repeat the steps to add node events or return parameters in the flow session.
  2. Click Save to save the details of the request.
  3. Use the Test button to launch the Node Configuration dialog where you can preview the configuration settings of the node.

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. The text box is the default type.
FieldDescription
Text box Regex Validation – add a regex validation string
Test Regex- check if the regex validation string is valid
Selection box Add New – use to add values to the selection box
Display Name – the name of the option in the selection box
* Value – value of the option in the selection box
Date and time Date format – format of the date
Date-Time Separator – separator between date and time
* Time format – format of time
  1. Mark the parameter as Mandatory Parameter if it is a required parameter. It is the default selection.
  2. Provide text that you want as Tooltip.
  3. Click Save to save the node configuration.
  4. 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.

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.

891

Throttling

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.