webMethods.io Integration provides a set of predefined and configurable connectors, for example, Salesforce, StrikeIron, ServiceNow, Coupa, and so on and the connectors allow you to connect to a particular SaaS provider. Each connector uses an account to connect to the provider’s back end and perform operations, and also comes with a predefined set of operations. You can also create your own custom operations while creating a FlowService.
To access the Predefined Connectors page, from the webMethods.io Integration navigation bar, click Projects, select a project, click Connectors, and then click Predefined.
The right side of the page displays the predefined connectors available in webMethods.io Integration. Click the drop-down arrow beside a connector to view the accounts configured for that connector. The Used in column displays the Workflows, FlowServices, and Operations where the connector is used.
You can create an account for a connector from the following pages:
- On the Predefined Connectors page, click on a connector available on the Available Connectors panel, and specify the configuration parameters.
- On the Predefined Connectors page, point to a connector row, click on the New Account option, and specify the configuration parameters.
- While creating or editing a FlowService, select an account, choose an action, and then click the Configure Accounts option to create an account inline.
- While creating or editing a Workflow, drop a connector to the canvas, click the Settings icon, select an action, and then in the Connect to
field, click the + option to specify the configuration parameters for the connector.
Adding Accounts and Custom Operations for Predefined Connectors
Let us see how to create a custom operation and an account for a predefined connector, Coupa. Coupa is a cloud-based business spend management platform that helps you gain real-time spend visibility, control, compliance, and agility over all your business spends.
From the webMethods.io Integration navigation bar, click Projects > <Select a Project> > Connectors > Predefined.
Add an account for Coupa.
Provide the login endpoint to initiate communication with the SaaS provider.
Provide the API key received from the user account.
The Coupa connector will be added in the Predefined Connectors list.
Click the FlowServices tab and on the FlowServices page, click the + icon.
Provide a name, for example, CreateItems and an optional description for the FlowService.
Type Coupa in the search box, select the Coupa connector, and then in the Type to choose action field, select Add Custom Operation.
Do the steps as shown in the following images to create the CreateCoupaItems custom operation.
Click and provide the field values.
Run the FlowService and view the execution results.
Enabling invalid/disabled accounts
By creating an account for an external web service/application (for example, Gmail, Dropbox, Smartsheet, etc.), you authorize webMethods.io Integration to perform specific tasks on your behalf. However, occasionally, the configured accounts get disabled and/or can become invalid due to several reasons, such as:
- User roles and permissions changed
- User doesn’t have the required access permissions
- Login credentials for the external web service/application changed and not updated in webMethods.io Integration
- User has manually disabled the account connection. Know more about Disabling Accounts.
If the configured account becomes invalid, webMethods.io Integration will fail to access data from the associated external web service/application to perform the specified tasks, thereby stopping the workflow/FlowService execution.
In such cases, webMethods.io Integration allows you to re-establish the account connection with just one click. To do so, from the webMethods.io Integration navigation bar,
- Click Projects, locate the relevant project, click Connectors, and then click Predefined.
- Click on the drop-down arrow located at the left of the connector icon of which account connection you want to enable. You will see the list of configured accounts for that connector. Here, in our example, we have selected the Coupa connector.
- Next, hover over the account name of this disbaled account connection. You will see three icons - Enable, Edit, and Delete. Click on the Enable icon.
Doing this will successfully re-establish the connection and enable the external web service/application account with webMethods.io Integration. Also, on clicking the Enable icon, the warning sign disappears. You can now continue to execute your workflows/FlowServices as you would normally do.
Here, we see two accounts are configured for the application - Coupa. Please note that there is a warning sign beside the name of the first Coupa account - Coupa_1. This warning sign indicates that the corresponding Coupa account is disabled.
Note: Changing login credentials for an external web service/application will disable the account connection in webMethods.io Integration, thereby enabling the option to re-establish the connection. However, in this case, the Enable button will not work as expected and you will have to reconnect to the external web service/application by authorizing webMethods.io Integration to access data. Click here to know more about accounts.
webMethods.io Integration allows you to stop a workflow/FlowService from being executed.
Let’s say you have many the same account configured for many workflows/FlowServices and you don’t want that account to be used anymore. Here, instead of removing the account from individual workflow/FlowService, you can simply disable it from a central place. This can be achieved by disabling an account of an application/external web service. Disabling an account of an application/external web service can be useful for several reasons, such as:
- A workflow/FlowService exceeds the request limit to an application/external web service, thereby overwhelming the application/external web service.
- The application/external web service to which your workflow/FlowService sends requests faces server down issues.
- A workflow/FlowService is not critical and you would want to halt the execution activity temporarily.
Disabling an account of an application/external web service is temporary. You can re-enable the account anytime as per your requirements. Let’s now understand how to disable an account of an application/external web service and then enable the same account in detail.
- Click Projects, locate the relevant project, click Connectors, and then click Predefined.
- Click on the drop-down arrow located at the left of the connector icon of which account connection you want to disable. You will see the list of configured accounts for that connector. Here, in our example, we have selected the Cumulocity connector.
- Hover over the account name of which connection you want to disable. You will see three icons - Disable, Edit, and Delete. Click on the Disable icon.
Doing this will successfully disable the connection and disable the external web service/application account with webMethods.io Integration.
On disabling the account, a warning icon appears beside the name of the account. This icon indicates that the account is disabled.
- To re-enable the disabled account, simply hover over the account name and you will see three icons - Enable, Edit, and Delete. Click on the Enable icon. Doing this will successfully re-establish the connection and enable the external web service/application account with webMethods.io Integration. You can now continue to execute your workflows/FlowServices as you would normally do.
Using Dynamic Accounts in Predefined Operations
The Dynamic Account feature enables you to dynamically override certain details of the account being used to run a predefined operation of a connector.
- Currently, the dynamic account feature is enabled for certain operations of following predefined connectors:
- Sitecore Content Hub
- You can also enable dynamic account feature for custom actions created under custom REST connectors. Learn more about it here.
When the dynamic account feature is enabled for any predefined operation by webMethods.io Integration, it enables you to select the account to execute a connector operation and then override certain details of the selected account at the time of operation configuration.
Perform the following steps to use dynamic account feature in a predefined operation:
Drag-and-drop a connector containing dynamic account-enabled predefined operation from the Connectors panel on the canvas, double-click it, and select the predefined operation you want to run.
Add/select the account you want to use to run the selected operation.
For all the dynamic account-enabled operations you can view the highlighted message.
In the Action configure form that appears, provide values for operation input fields.
Provide values for the relevant fields listed under the $connection block and then click Next.
The values you provide for these fields override the default values of your selected account.
- Only encrypted fields (such as, Password, Client Secret) are mandatory under the $connection block. You can optionally keep the rest of the fields under the $connection block blank, in which case, webMethods.io Integration uses the default field values provided at the time of creating the selected account.
- If you do not want to override the account details, you can keep the $connection block blank. So, at the run time, webMethods.io Integration uses the selected account with its default values to run the operation.
Once this is done, optionally Test the operation, and then click Done.
This takes you back to the canvas.
Now whenever you connect this operation to any workflow and run it, webMethods.io Integration automatically overrides the default values with dynamic values while creating the connection. This connection with the modified values is then used to run the custom operation.
Troubleshooting tips on Account configurations
Let us see some of the most common scenarios you may come across while configuring an Account.
I see connection reset errors. What is the root cause of these errors?
The root cause of connection reset errors is stale connections, typically in the case of HTTP connection reuse. It is recommended to set the Keep Alive Interval to two minutes or lower.
Time Out Exceptions
I see a transaction has failed with the following exception: ERROR_INVOKING_CLOUD_SERVICE: An IO or timeout exception is encountered for invoke “xxx” method.
What is the root cause and the resolution?
The root cause may be linked to stale connections or a low response timeout value. To handle stale connections, set the Keep Alive Interval to two minutes or lower. To handle receipt of large payloads or a slow network impacting the responsiveness of the back end, increase the Response Timeout value, for example, to five minutes or higher.
Session Expired or Invalid Session ID
I am using the Salesforce Credential based account configuration and I see the following invalid_session_id errors while executing operations. How can I prevent an invalid session time out?
INVALID_SESSION_ID: Invalid Session ID found “message”: “Session expired or invalid”, “errorCode”: INVALID_SESSION_ID”
Salesforce operation execution fails sometime with Invalid Session ID found error
Invalid Session ID found in SessionHeader: Illegal Session. Session not found. This error usually occurs after a session expires or a user logs out. Decoder: DataInDbSessionKeyDecoder
These errors are observed if the Salesforce CRM Account Session Management or Session Timeout configurations are not configured correctly for the Credentials based authentication type. When you add an account in webMethods.io Integration by selecting the authentication type as Credentials, the Session Management and Session Timeout fields come pre-configured with values fixed and 14 mins. The value 14 mins is in accordance with the minimum session timeout configuration allowed by Salesforce which is 15 mins. In case the session timeout in Salesforce is configured to a higher value, for example, 12 hours, then it is recommended to configure the Session Timeout field in the webMethods.io Integration account to a value less than 12 hours. This is to ensure that the session is refreshed before it is expired by Salesforce.
Disabled Connection Issue
Sometimes integrations start failing and I see the following cloud connection disabled errors. Why do they appear and what is the resolution?
DISABLED_CLOUD_CONNECTION: Connection xxx is disabled
INVALID_LOGIN: Invalid username, user not active
Connection disabled errors may appear due to the following reasons:
- Salesforce back end account password has been changed or has expired: In this case, check if the password is still valid.
- Salesforce login limit is breached: If 3600 login calls are sent to Salesforce in 15 minutes, then depending on the configured Lockout effective period in Salesforce, the integration fails, and the DISABLED_CLOUD_CONNECTION: Connection xxx message appears. For example, If 3600 login calls are sent to Salesforce in 15 minutes, and you have set the Lockout effective period to 60 minutes, then from the 16th minute till the 60th minute, all integrations will fail. Usually credentials based connections get disabled once the Salesforce login limit is breached. You may have reached the login limit quota for the back end.
Minimizing the login calls to Salesforce
Salesforce allows 3600 logins per hour. In webMethods.io Integration, select the Enable Connection Pooling option to enable connection pooling. Also adjust the Minimum Pool Size, Maximum Pool Size, and the Expire Timeout (msec) values.
Expire Timeout ensures that a connection in the webMethods.io Integration Account pool is kept alive for the configured time interval after the Account is created. In the absence of the Expire Timeout configuration, the connection will be invalidated immediately to maintain the Minimum Pool Size as one. The intention is to limit the number of login requests, so the recommendation is to keep the Expire Timeout value equal to the Session Timeout value, because the connection is anyways invalidated after Session Timeout. For example, if the session timeout in Salesforce back end is configured to two hours, specify the Expire Timeout and the Session Timeout values in the webMethods.io Integration Account Configuration screen to be slightly less than two hours.
|Account Configuration Fields||Value|
|Session Timeout||Slightly less than the Salesforce back end session timeout settings. For example, 119 minutes, if the Salesforce back end session timeout value is 120 minutes.|
|Keep Alive Interval||Two minutes or lower.|
|Response Timeout||Five minutes or higher.|
Do the following if your Salesforce login limit is breached
If your Salesforce logins have exceeded 3600 logins/hour, then your Salesforce account gets disabled. This is usually observed in the case of credentials-based authentication connection with the back end.
In this scenario, login to your Salesforce back end account, go to Setup > Manage User > Users, select the User profile, go to the Password Policies section, and check the time configured for the Lockout effective period field. The Lockout effective period is the time for which the Salesforce back end account will be locked once the login limit is breached. You can either wait till the time specified in the Lockout effective period field has passed or you can configure a different lockout value as per your need.
What do I do if I see the UNABLE_TO_RETRIEVE_CONNECTION_FROM_POOL error while enabling Accounts or executing Operations?
Increase the Maximum Pool Size or the Block Timeout values.
Regarding the maximum pool size, when the connection pool has reached its maximum number of connections, the connector will reuse any inactive connections in the pool, or if all connections are active, it will wait for a connection to become available. Increasing the Block Timeout value increases the time webMethods.io Integration will wait to obtain a connection with the SaaS provider before the connection times out and returns an error.
For example, if you have a pool with Maximum Pool Size of 20 and if you receive 30 simultaneous requests for a connection, 10 requests will be waiting for a connection from the pool. Now if you set the Block Timeout to 5000 msec, the 10 requests will wait for a connection for 5000 msec or 5 seconds before they time out and return an error. If the services using the connections require 10 seconds to complete and return connections to the pool, the pending requests will fail and return an error message stating that no connections are available.