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:

Note
Click here to see some of the most common scenarios you may come across while configuring an Account.
Click here for information on the account configuration fields.

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:

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,

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

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.

Note
Changing login credentials for an external web service/application will disable the account connection in IBM webMethods 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 IBM webMethods Integration to access data. Know more about Accounts.

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:

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.

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.

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.

Note

Currently, the dynamic account feature is enabled for certain operations of the following predefined connectors:

  • Sitecore Content Hub
  • MessageBird
  • Docuware
  • RSS

You can also enable the 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 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.

Note
  • 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, IBM webMethods 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, IBM webMethods 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, 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:

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.

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