Adapter Connections

Overview

This chapter describes how to configure and manage Adapter for Salesforce connections. For more information about how adapter connections work, see Adapter Connections.

For instructions on how to configure the proxy servers, see the IBM webMethods Integration Server Administrator’s Guide for your release.

Before Configuring or Managing Adapter Connections

About this task

To prepare to configure or manage an adapter connection

Procedure

Install Integration Server Administrator and Adapter for Salesforce on the same machine. For details, see Installing, Upgrading, and Uninstalling IBM webMethods Adapter for Salesforce.
Make sure you have webMethods administrator privileges so that you can access Adapter for Salesforce's administrative screens. For information about setting user privileges, see the IBM webMethods Integration Server Administrator’s Guide for your release.
Start Integration Server and Integration Server Administrator, if they are not already running.
Using Integration Server Administrator, make sure the WmSalesforceAdapter package is enabled. See Enabling Adapter Connections for instructions.
Using Designer, create a user-defined package to contain connections, if you have not already done so. See Managing the Adapter Package for details.
Create your connections, as described in Configuring Adapter Connections.

Configuring Adapter Connections

About this task

When you configure Adapter for Salesforce connections, you specify information that Integration Server uses to connect to Salesforce.com and Database.com. Using Integration Server Administrator, you can configure two types of Adapter for Salesforce connections: Salesforce.com or Salesforce.com OAuth.

Adapter for Salesforce connections can use HTTP/HTTPS proxy servers registered with Integration Server to connect to Salesforce.com. To enable the proxy settings, in Integration Server Administrator, set the watt.adapter.salesforce.useproxy watt property to true. By default, the property is set to false. If the watt property is set to true, a Adapter for Salesforce connection automatically uses the default proxy server registered with Integration Server, provided that the proxy server is enabled. If you change the proxy server settings in the Integration Server configuration parameters, restart Integration Server because the settings are cached at the Integration Server level.

For information about configuring the watt.adapter.salesforce.useproxy watt property, see the IBM webMethods Integration Server Administrator’s Guide for your release.

Note: In this section, when we talk about an adapter connection to Salesforce.com, we imply an adapter connection to either Salesforce.com, or Database.com. For more information about Database.com, see About the Adapter.

Configuring a Salesforce Connection

About this task

To configure a Salesforce connection

Procedure

In Integration Server Administrator, select Adapters> IBM webMethods Adapter for Salesforce.
On the Connections screen, select Configure New Connection.
On the Connection Types screen, select IBM webMethods Adapter for Salesforce Connection to display the Configure Connection Type screen.

In the Configure Connection Type > IBM webMethods Adapter for Salesforce section, provide values for the following parameters:

Parameter	Description
Package	The package in which to create the connection. You must create the package using Designer before you can specify it using this parameter. For general information about creating packages, see the IBM webMethods Service Development Help for your release. Note: Create the connection in a user-defined package rather than in the WmSalesforceAdapter package. See Managing the Adapter Package for other important considerations when creating packages for Adapter for Salesforce.
Folder Name	The folder in which to create the connection.
Connection Name	The name you want to give the connection. Connection names cannot have spaces or use special characters reserved by Integration Server and Designer. For more information about the use of special characters in package, folder, and element names, see the IBM webMethods Service Development Help for your release.

In the Connection Properties section, provide values for the following parameters:

Parameter	Description
Endpoint URL	Defines the login endpoint for initiating communications with Salesforce.com. The default URL for the WSDL version 25 is: `https://login.salesforce.com/services/Soap/u/25.0` Adapter for Salesforce enables users to specify an alternate URL when using the Salesforce.com Sandbox or a testing environment. To access the organization's Salesforce.com sandbox, specify the following URL: `https://test.salesforce.com/services/Soap/u/25.0`
User Name	Identifies the user name for the Salesforce.com or Database.com user account that you want the adapter to access. Typically, the user name is an e-mail address.
Password Retype Password	Identifies the password associated with User Name and the user's security token. For example, if the password is "mypassword" and the security token is "XXXXXXXXXX", specify the following for Password and Retype Password: `mypasswordXXXXXXXXXX` Salesforce.com or Database.com require a security token for access via the Force.com Web service API. To obtain the security token from the Salesforce.com or Database.com user interface, select Setup; then in the My Personal Information section of the screen, click Reset your security token. Salesforce.com resets the security token and sends an e-mail message with the new security token to the registered user. Note: The security token you specify in the connection is valid until you reset it, change your password, or have your password reset. The security token is not required, if the endpoint URL is a Salesforce.com sandbox.
Connector Timeout (sec)	Defines the number of seconds that Adapter for Salesforce waits for a response from Salesforce.com before reporting a connection timeout. This is a SOAP connection timeout. The default is 60 seconds. The adapter expects a positive integer value. A value of 0 means no timeout.
Session Timeout (min)	Defines the number of minutes to maintain a Salesforce.com user session before performing a re-login to keep the session alive. The default is 30 minutes. Specify the same value here as in the Security Controls setup area in the Salesforce.com user interface, to allow the adapter to automatically re-login to prevent a session from expiring. After a session is established, Salesforce.com automatically expires the session after the number of minutes specified in the Security Controls setup area in the Salesforce.com user interface.
Use Compression	Indicates whether you want the adapter to enable compression in the SOAP request and response messages sent to Salesforce.com. Select `false` to disable compression. This is the default. Select `true` to enable compression. As defined by the HTTP 1.1 specification to indicate that compression is supported, the adapter includes "Accept-Encoding: gzip, deflate" in the HTTP header of the request message. For compressed response messages, the HTTP header includes "Content-Encoding: deflate" or "Content-Encoding: gzip", as appropriate.

In the Connection Management Properties section, provide values for the following parameters:

Parameter	Description
Enable Connection Pooling	Enables the adapter to use connection pooling. The default is `true`. See Connection Pools for more information about connection pooling in the adapter. If you plan to enable connection pooling in a clustered environment, consider the connection pool size. For details, see Considerations When Configuring Connections with Connection Pooling Enabled.
Minimum Pool Size	The minimum number of connection objects that remain in the connection pool at all times. When the adapter creates the pool, it creates this number of connections. The default is `1`.
Maximum Pool Size	The maximum number of connection objects that can exist in the connection pool. When the connection pool has reached its maximum number of connections, the adapter will reuse any inactive connections in the pool or, if all connections are active, it will wait for a connection to become available. The default is `10`.
Pool Increment Size	If connection pooling is enabled, this parameter specifies the number of connections by which the pool will be incremented if connections are needed, up to the maximum pool size. The default is `1`.
Block Timeout (msec)	If connection pooling is enabled, this parameter specifies the number of milliseconds that Integration Server will wait to obtain a connection before it times out and returns an error. The default is `1000`.
Expire Timeout (msec)	If connection pooling is enabled, this parameter specifies the number of milliseconds that an inactive connection can remain in the pool before it is closed and removed from the pool. For example, to specify 10 seconds, specify `10000`. Enter `0` to specify no timeout. The default is `1000`. Note: The adapter will never violate the Minimum Pool Size parameter. These connections remain in the pool regardless of how long they are inactive.
Startup Retry Count	If connection pooling is enabled, this parameter specifies the number of times that the system should attempt to initialize the connection pool at startup if the initial attempt fails, before issuing an AdapterConnectionException. The default is `0`.
Startup Backoff Timeout (sec)	If connection pooling is enabled, this parameter specifies the number of seconds to wait between each attempt to initialize the connection pool. The default is `10`.

Click Save Connection.

The connection you created appears on the adapter's Connections screen.
Be sure to enable the connection before you create adapter services that use it. See Enabling Adapter Connections for instructions.

Configuring a Salesforce OAuth Connection

About this task

To configure a Salesforce OAuth connection

Procedure

In Integration Server Administrator, select Adapters > IBM webMethods Adapter for Salesforce.
On the Connections screen, select Configure New Connection.
On the Connection Types screen, select IBM webMethods Adapter for Salesforce OAuth Connection to display the Configure Connection Type screen.

In the Configure Connection Type>IBM webMethods Adapter for Salesforce section, provide values for the following parameters:

Parameter	Description
Package	The package in which to create the connection. You must create the package using Designer before you can specify it using this parameter. For general information about creating packages, see the IBM webMethods Service Development Help for your release. Note: Create the connection in a user-defined package rather than in the WmSalesforceAdapter package. See Managing the Adapter Package for other important considerations when creating packages for Adapter for Salesforce.
Folder Name	The folder in which to create the connection.
Connection Name	The name you want to give the connection. Connection names cannot have spaces or use special characters reserved by Integration Server and Designer. For more information about the use of special characters in package, folder, and element names, see the IBM webMethods Service Development Help for your release.

In the Connection Properties section, provide values for the following parameters:

Parameter	Description
Login Endpoint URL	Defines the login endpoint for initiating communications with Salesforce.com using the OAuth 2.0 framework. The default URL is: `https://login.salesforce.com/services/oauth2/token`
User Name	Identifies the user name for the Salesforce.com or Database.com user account that you want the adapter to access. Typically, the user name is an e-mail address.
Password Retype Password	Identifies the password associated with User Name and the user's security token. For example, if the password is "mypassword" and the security token is "XXXXXXXXXX", specify the following for Password and Retype Password: `mypasswordXXXXXXXXXX` Salesforce.com or Database.com require a security token for access via the Force.com Web service API. To obtain the security token from the Salesforce.com or Database.com user interface, select Setup; then in the My Personal Information section of the screen, click Reset your security token. Salesforce.com resets the security token and sends an e-mail message with the new security token to the registered user. Note: The security token you specify in the connection is valid until you reset it, change your password, or have your password reset. The security token is not required, if the endpoint URL is a Salesforce.com sandbox.
WSDL Version	The version of the Salesforce.com Partner WSDL. The connection will pick this parameter from the partner jar file in the `Integration Server_directory`\packages\WmSalesforceAdapter\code\jars directory.
Client ID	In Salesforce.com, your application's client identifier (also known as consumer key). To obtain the client ID, in the Force.com administration console, go to Setup > Develop > Remote Access, and click New to create a new remote access application. After saving the remote access application, you obtain the new credentials for the client ID. To create the remote access application, provide values for the following parameters at Salesforce.com: Application. The remote access application name. Contact Email. A valid email ID. Callback URL. The callback URL is the same as your application’s callback URL. The URL must begin with https://. Note: The callback URL is an OAuth parameter. It is not used by the adapter. However, the OAuth framework client libraries expect this parameter.
Client Secret	In Salesforce.com, your application's client secret (also known as consumer secret).
Retype Client Secret	Confirm the client secret by retyping it.
Connector Timeout (sec)	Defines the number of seconds that Adapter for Salesforce waits for a response from Salesforce.com before reporting a connection timeout. This is an HTTP connection timeout. The default is 60 seconds. The adapter expects a positive integer value. A value of 0 means no timeout.
Session Timeout (min)	Defines the number of minutes to maintain a Salesforce.com user session before performing a re-login to keep the session alive. The default is 30 minutes. Specify the same value here as in the Security Controls setup area in the Salesforce.com user interface, to allow the adapter to automatically re-login to prevent a session from expiring. After a session is established, Salesforce.com automatically expires the session after the number of minutes specified in the Security Controls setup area in the Salesforce.com user interface.

In the Connection Management Properties section, provide values for the following parameters:

Parameter	Description
Enable Connection Pooling	Enables the adapter to use connection pooling. The default is `true`. See Connection Pools for more information about connection pooling in the adapter. If you plan to enable connection pooling in a clustered environment, consider the connection pool size. For details, see Considerations When Configuring Connections with Connection Pooling Enabled.
Minimum Pool Size	The minimum number of connection objects that remain in the connection pool at all times. When the adapter creates the pool, it creates this number of connections. The default is `1`.
Maximum Pool Size	The maximum number of connection objects that can exist in the connection pool. When the connection pool reaches its maximum number of connections, the adapter will reuse any inactive connections in the pool or, if all connections are active, it will wait for a connection to become available. The default is `10`.
Pool Increment Size	If connection pooling is enabled, this parameter specifies the number of connections by which the pool will be incremented if connections are needed, up to the maximum pool size. The default is `1`.
Block Timeout (msec)	If connection pooling is enabled, this parameter specifies the number of milliseconds that Integration Server will wait to obtain a connection before it times out and returns an error. The default is `1000`.
Expire Timeout (msec)	If connection pooling is enabled, this parameter specifies the number of milliseconds that an inactive connection can remain in the pool before it is closed and removed from the pool. For example, to specify 10 seconds, specify `10000`. Enter `0` to specify no timeout. The default is `1000`. Note: The adapter will never violate the Minimum Pool Size parameter. These connections remain in the pool regardless of how long they are inactive.
Startup Retry Count	If connection pooling is enabled, this parameter specifies the number of times that the system should attempt to initialize the connection pool at startup if the initial attempt fails, before issuing an AdapterConnectionException. The default is `0`.
Startup Backoff Timeout (sec)	If connection pooling is enabled, this parameter specifies the number of seconds to wait between each attempt to initialize the connection pool. The default is `10`.

Click Save Connection.

The connection you created appears on the adapter's Connections screen.
Be sure to enable the connection before you create adapter services that use it. See Enabling Adapter Connections for instructions.

Dynamically Changing a Service's Connection at Run Time

About this task

You can run an adapter service using a connection other than the default connection that was associated with the service when it was created. To override the default, you must code your flow service to pass a value through the pipeline into the adapter service's $connectionName field.

For example, you have a flow service that creates a new account for the Account Salesforce object in the Salesforce.com production area. However, for testing purposes you want the flow service to have the capability to create the account in the Salesforce.com Sandbox. At run time, you want the flow service to determine programmatically whether to create the account in the production area or the Sandbox. Set up your flow service to have a Target variable so that it can branch its logic based on the value in Target:

If Target contains the value production, the flow service does not specify a value for the $connectionName pipeline variable, which causes the adapter service to use its default connection to the production area.
If Target contains the value test, the flow services sets the $connectionName variable to the connection for the Sandbox so that the adapter service creates the account in the Sandbox.

Alternatively, you can use the configured connection for an adapter service, but at run time override the Salesforce.com user credentials defined in the connection. To override the user credentials, you must code your flow service to pass values through the pipeline into the adapter service's username and password fields.

Note: When using the Salesforce OAuth connection for an adapter service, changing the OAuth connection user credentials (username and password) at runtime causes the adapter to create a normal Salesforce.com connection with these credentials.

For more information, see Changing the Connection Associated with an Adapter Service at Run Time.

Viewing Adapter Connection Parameters

About this task

You can view a connection's parameters from Integration Server Administrator and Designer.

Viewing Parameters Using Integration Server Administrator

About this task

To view the parameters for an adapter connection using Integration Server Administrator

Procedure

In the Adapters menu in Integration Server Administrator's navigation area, click IBM webMethods Adapter for Salesforce.

When using the adapter with Integration Server 8.2 and later, you can sort and filter the list of connections that appears on the Connections screen.
- To sort information on the Connections screen, click the Up and Down arrows at the top of the column you want to sort.
- To filter the list of connections:
  1. On the Connections screen, click Filter Connections.
  2. Type the criterion by which you want to filter into the Filter criteria box. Filtering is based on the node name, not the connection alias. To locate all connections containing specific alphanumeric characters, use asterisks (*) as wildcards. For example, if you want to display all connections containing the string "abc", type *abc* in the Filter criteria box.
  3. Click Submit. The Connections screen displays the connections that match the filter criteria.
  4. To re-display all connections, click Show All Connections.
The Connections screen appears, listing all the current connections. You can control the number of connections that are displayed on this screen. For more information, see Controlling Pagination.
On the Connections screen, click for the connection you want to see.

The View Connection screen displays the parameters for the connection. For descriptions of the connection parameters, see the table of parameters in Configuring Adapter Connections.
Click Return to IBM webMethods Adapter for Salesforce Connections to return to the Connections screen.

Viewing Parameters Using Designer

About this task

To view the parameters for an adapter connection using Designer

Procedure

From the Designer navigation area, open the package and folder in which the connection is located.
Double-click the connection you want to view.

The parameters for the connection appear in the Connection Information tab. For descriptions of the connection parameters, see the table of parameters in Configuring Adapter Connections.

Editing Adapter Connections

About this task

Use Integration Server Administrator to redefine parameters for a connection.

To edit an adapter connection

Procedure

Disable the connection you want to edit. See Disabling Adapter Connections for instructions.
In Integration Server Administrator, select Adapters > IBM webMethods Adapter for Salesforce.
On the Connections screen, click for the connection you want to edit.

In the Edit Connection screen, update the parameters by typing or selecting the values you want to specify. For descriptions of the connection parameters, see Configuring Adapter Connections.
Click Save Changes to save the connection and return to the Connections screen.
Enable the connection you edited. See Enabling Adapter Connections for instructions.

Copying Adapter Connections

About this task

You can copy an existing Adapter for Salesforce connection to create a new connection with the same or similar connection properties without retyping all properties for the new connection.

To copy an adapter connection

Procedure

In Integration Server Administrator, select Adapters > IBM webMethods Adapter for Salesforce.
On the Connections screen, click for the connection you want to copy.

The Copy Connection screen displays the current parameters for the connection you want to copy. Name the new connection and edit any connection parameters as needed by typing or selecting the values you want to specify. For descriptions of the connection parameters, see Configuring Adapter Connections.
Click Save Connection Copy to save the connection and return to the Connections screen.

Deleting Adapter Connections

About this task

You can delete Adapter for Salesforce connections that you no longer want to use.

When you delete a Adapter for Salesforce connection, the adapter services that are defined to use the connection will no longer work. To assign a different connection to an adapter service and re-use the service, use the webMethods setAdapterServiceNodeConnection built-in service. For more information, see Changing the Connection Associated with an Adapter Service at Design Time.

To delete an adapter connection

Procedure

Disable the connection you want to delete. See Disabling Adapter Connections for instructions.
In Integration Server Administrator, select Adapters > IBM webMethods Adapter for Salesforce.
On the Connections screen, click for the connection you want to delete.

Integration Server deletes the adapter connection.

Enabling Adapter Connections

About this task

Adapter connections must be enabled before you can create adapter services or adapter notifications for those connections.

Note: When you reload a package that contains enabled connections, the connections will automatically be enabled when the package reloads. If the package contains connections that are disabled, they will remain disabled when the package reloads.

To enable an adapter connection

Procedure

In Integration Server Administrator, select Adapters > IBM webMethods Adapter for Salesforce.
On the Connections screen, click No in the Enabled column for the connection you want to enable.

Integration Server Administrator enables the adapter connection and displays and Yes in the Enabled column.

Disabling Adapter Connections

About this task

Adapter connections must be disabled before you can edit or delete the connections.

To disable an adapter connection

Procedure

In Integration Server Administrator, select Adapters > IBM webMethods Adapter for Salesforce.
On the Connections screen, click Yes in the Enabled column for the connection you want to disable.

Integration Server Administrator disables the adapter connection and displays No in the Enabled column.