Custom Node Integration
Understand how to configure Custom Node Integrations with Rest/SOAP APIs
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:
- Click Assets > Integrations > Add Integration > Custom Node on the services dashboard.
- 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. - 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.
- Configure the request details of the method.
- 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:
- 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.
Field | Description |
---|---|
Parameter | Variable parsed from the URL |
Parameter Type | Specify If the parameter is Static or Dynamic |
Parameter Value | This is applicable if the parameter is static. Provide value. |
Field Name | This 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.
- 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
Field | Description |
---|---|
Username/Password | Login credentials that you want to use for authentication |
Parameter Value Type | Specify If the parameter is Static or Dynamic |
Parameter value | This is applicable if the parameter is static. Provide value. |
Field Name | This 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.
Field | Description |
---|---|
Username | Username to authenticate the request |
Realm | String from the server within the www-Authenticate response header |
Password | The password to authenticate the request |
Nonce | Unique string from the server within the www-Authenticate response header |
Algorithm | String that indicates a pair of algorithms used to produce the digest and a checksum |
QOP | The 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 Count | The 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 Nonce | An 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. |
Opaque | A 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.
Field | Description |
---|---|
Access_Key | Unique access key for an account used to send the request |
Secret_Key | The unique secret key for an account used to send the request |
Region | The region that receives the request |
Service_Name | Service 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
- Authorization code - server issues the token in the context of a user.
- Client credentials - grant type is used to obtain an access token outside of the context of a user.
Field | Description |
---|---|
Consumer ID | Unique identifier of the consumer obtained during the registration process |
Grant Type | Type 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. |
Scope | Scope of the access request (multiple space-separated values). This is optional. |
Access Token URL | Endpoint for the resource server, which exchanges the authorization code for an access token |
Access token has a limited validity | Specifies if the token has a limited validity and must be provided by the authorization provider. |
Validity | Validity of the token |
Refresh URL Token | It should be provided by the authorization provider. It ensures smooth functioning of authorization in the case provided access token has limited validity. |
Advance Settings | Toggle button that allows you to enable or disable advanced settings |
Access Token URL Method | An additional method for the access token |
Access Token URL Parameter type | Type of access token URL parameter – Body or URL |
Access Token URL Headers | Additional URL header parameters for the access token |
Get Access Token | Button to retrieve the access token |
Access Token | Displays the refresh token |
Refresh Token | Displays the refresh token |
Client Authentication | Value of Client Authentication is defined by the authorization provider’s API. Send client credentials in body is selected by default. |
Validity | The validity of the token |
- 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:
Field | Description |
---|---|
Browse Certificate | Browse and upload the key store certificate |
Select File Format | Select the key store file format – JKS or PKCS12 |
Store Password | The password to access the store |
Key Password | The password to access the key |
Name | Enter a name for the certificate |
Validate | Click the button to extract the validity information from the certificate |
Valid From | The 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 Till | The 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. |
Identifier | Unique 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:
Field | Description |
---|---|
Browser Certificate | Browse and upload the key store certificate |
Select File Format | Select the key store file format – JKS or PKCS12 |
Store Password | The password to access the store |
Name | Enter a name for the certificate |
Validate | Click the button to extract the validity information from the certificate |
Valid From | The 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 Till | The 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. |
Identifier | Unique 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.
Protocol | Description |
---|---|
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.0 | Uses HMAC and requires DSS/DH support |
TLS 1.1 | Uses explicit implicit initialization vector (IV) to protect against Cipher block chaining attacks |
TLS 1.2 | Uses 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.
- 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:
Field | Description |
---|---|
Parameter | Name of the parameter or variable |
Parameter Value Type | Type of parameter – Static or Dynamic |
Parameter Value | Value of the parameter/variable This is applicable only for a static parameter. |
Field Name | Name of the field to which you can pass a value This is applicable only for a dynamic parameter. |
- 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:
Field | Description |
---|---|
Parameter | Name of the parameter or variable |
Parameter Value Type | Type of parameter – Static or Dynamic |
Parameter Value | Value of the parameter/variable This is applicable only for a static parameter. |
Field Name | Name of the field to which you can pass a value This is applicable only for a dynamic parameter. |
- 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:
Field | Description |
---|---|
Parameter | Name of the parameter or variable |
Parameter Value Type | Type of parameter – Static or Dynamic |
Parameter Value | Value of the parameter/variable This is applicable only for a static parameter. |
Field Name | Name of the field to which you can pass a value This is applicable only for a dynamic parameter. |
- 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.- 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.
- 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.
- Fill in the required details and Configure Node Events.
- 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."
- Click Save to save the details of the request.
- 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.
- Specify the Information Text. This is optional.
This is the description of the node and it appears on the Node Configuration dialog. - 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. - Select the Field Type for each parameter – Text box, Selection box, or Date and time. Text box is the default type.
Field | Description |
---|---|
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 |
- Mark the parameter as Mandatory Parameter if it is a required parameter. It is the default selection.
- Provide text that you want as Tooltip.
- Click Save to save the node configuration.
- 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.
- 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. - Select the required methods within the WSDL file and click Import to import those methods into the custom node.
- Configure the request details of the method.
- 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.
Updated 2 months ago