Predefined Connectors

Overview

IBM webMethods 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 Flow service.

To access the Predefined Connectors page, from the IBM webMethods Integration navigation bar, click Projects, select a project, click Connectors, and then click Predefined.

The right side of the page displays the available predefined connectors. Click the drop-down arrow beside a connector to view the accounts configured for that connector. The Used in column displays the workflows, flow services, 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 Flow service, 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.

1. From the IBM webMethods Integration navigation bar, click Projects > <Select a Project> > Connectors > Predefined.

   

2. Select Coupa.

   

3. Add an account for Coupa.

   

4. Provide the login endpoint to initiate communication with the SaaS provider.

5. Provide the API key received from the user account.

6. Click Add.

   

   The Coupa connector will be added in the Predefined Connectors list.

7. Click the Flow services tab and on the Flow services page, click the + icon.

   

8. Provide a name, for example, CreateItems and an optional description for the Flow service.

   

9. Type Coupa in the search box, select the Coupa connector, and then in the Type to choose action field, select Add Custom Operation.

   

10. Do the steps as shown in the following images to create the CreateCoupaItems custom operation.

    

    

    

    

    

    

11. Click and provide the field values.

    

12. Run the Flow service and view the execution results.

    

Enabling invalid/disabled accounts

By creating an account for an external web service/application (for example, Gmail, Dropbox, Smartsheet, and so on), you authorize IBM webMethods 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 IBM webMethods Integration
• User has manually disabled the account connection. Know more about Disabling Accounts.

If the configured account becomes invalid, IBM webMethods Integration will fail to access data from the associated external web service/application to perform the specified tasks, thereby stopping the workflow/Flow service execution.

In such cases, IBM webMethods Integration allows you to re-establish the account connection with just one click. To do so, from the IBM webMethods 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.

Here, we see two accounts are configured for the application:

• Coupa. 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.

• 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 IBM webMethods Integration. Also, on clicking the Enable icon, the warning sign disappears. You can now continue to execute your workflows/flow services as you would normally do.

Disabling accounts

IBM webMethods Integration allows you to stop a workflow/flow service from being executed.

Let’s say you have many the same account configured for many workflows/Flow services and you don’t want that account to be used anymore. Here, instead of removing the account from individual workflow/Flow service, 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/Flow service 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/Flow service sends requests faces server down issues.
• A workflow/Flow service 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 the drop-down arrow located at the left of the connector icon for the 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 for the 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 IBM webMethods 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, 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 IBM webMethods Integration. You can now continue to execute your workflows/flow services 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.

When the dynamic account feature is enabled for any predefined operation by IBM webMethods 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 the dynamic account feature in a predefined operation:

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

   

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

3. In the Action configure form that appears, provide values for the operation input fields.

   

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

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, IBM webMethods 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.

Connection Reset

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?

Errors

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 IBM webMethods 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 IBM webMethods 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?

Errors

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 IBM webMethods 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 IBM webMethods 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 IBM webMethods Integration Account Configuration screen to be slightly less than two hours.

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 IBM webMethods 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.