Connector to Salesforce

With the Salesforce® connector, you can use commands to interact with Salesforce as part of a chain. For example, with this connector, you can:

• Upload, extract, and delete data in Salesforce via SOQL and bulk operations
• Create and manage Salesforce objects
• Update and create records in Salesforce

The connector interacts with all versions of Salesforce Sales Cloud:

• Salesforce Essentials®
• Salesforce Net Zero Cloud
• Lightning® Professional
• Lightning Enterprise
• Lightning Unlimited

Note: This connector is built by Workiva and connects to a third-party system. While our Support team can help configure this connector within your workspace, we are unable to troubleshoot or otherwise assist with any issues that originate outside of the Workiva platform.

Requirements

To make the connector available for use in your organization, an org security administrator must first enable it.

You can then secure your connection to Salesforce using one of the following methods:

• Salesforce OAuth authentication, using a client ID, secret, and scope
• Basic authentication, using a username and password
• Client credentials, using only a client ID and secret
  
  

Salesforce OAuth authentication

To connect to Workiva, you will need the client ID and secret from Salesforce as well as the connected app's OAuth scope.

OAuth authentication additionally authentication requires the use of a Salesforce connected app. To create this in Salesforce, set up the app and configure the following required settings:

• For Callback URL, enter one of the following that matches your AppSpot:
  
  • PROD - https://h.app.wdesk.com/s/wdata/oc/app/oauth/callback
  • EMEA - https://h.eu.wdesk.com/s/wdata/oc/app/oauth/callback
  • APAC - https://h.apac.wdesk.com/s/wdata/oc/app/oauth/callback
• Under Selected OAuth Scopes, include Perform requests on your behalf at any time (refresh_token, offline_access) and at least one other scope.
  
  

Basic authentication

To connect to Workiva, you will need the integration user's username, password, and security token from Salesforce.

Basic authentication requires an integration user with API-enabled permissions, in addition to permissions related to any tasks the connector will perform.

Note: To set the integration user's permissions in Salesforce, select Administer, Manage Users, Profiles, and select their profile.

1. Under Administrative Permissions, select API Enabled.
2. To enable the connector to perform a command, the user needs at least Read permissions to its related data. 
3. To perform bulk updates to Salesforce objects, the user needs Edit permissions to the object.
   
   

Client credential authentication

To connect to Workiva, you will need the client ID and secret from Salesforce.

Client credential authentication requires the use of a Salesforce connected app. To create this in Salesforce, set up the app using the client credentials flow.

Set up the Salesforce connector for OAuth authentication

OAuth authentication allows you to access Salesforce using a client ID and secret. Unlike the client credential login method, OAuth authentication includes a refresh token and requires a scope.

This method is recommended for longer-running commands that would otherwise time out using the client credentials method.

1. From Chain Builder, click Connections  compare_arrows, and then Create at the top right.
2. Under Connector Connection, select Salesforce and the default CloudRunner.
3. Under Basic Info, enter a unique name and description to help identify the connector.
4. Under Properties, enter the Salesforce instance or custom domain to connect to:
   

   Property	Details
   Instance	Enter the Salesforce instance to connect to. If your organization uses a custom Salesforce domain, leave blank. Note: In your Salesforce URL, the characters before salesforce.com—such as na73—represent the instance.
   Custom domain	Enter the custom Salesforce domain to connect to, if used. Note: To view your custom domain in Salesforce, select Company Settings, My Domain. A custom domain usually ends with .my.salesforce.com.

5. For Authentication Type, select Salesforce OAuth.
6. Enter the client ID, secret, and scope under Authentication, then click Connect.

   Note: When the connection to Salesforce succeeds, the connector's Refresh Token and Access Token automatically populate. If the connection fails, click Stop and wait to connect again.

   Note: All sensitive credentials are automatically encrypted and stored at AES-256 encryption.

7. Select the environments to use with the connection, and click Save.
8. To test the connection, create and run a chain with the connector's List Reports command, and verify it returns a valid output.

Set up the Salesforce connector for basic authentication

Basic authentication allows you to log in to Salesforce using an integration user's username and password.

1. From Chain Builder, click Connections  compare_arrows, and then Create at the top right.
2. Under Connector Connection, select Salesforce and the default CloudRunner.
3. Under Basic Info, enter a unique name and description to help identify the connector.
4. Under Properties, enter the Salesforce instance or custom domain to connect to:
   

   Property	Details
   Instance	Enter the Salesforce instance to connect to. If your organization uses a custom Salesforce domain, leave blank. Note: In your Salesforce URL, the characters before salesforce.com—such as na73—represent the instance.
   Custom domain	Enter the custom Salesforce domain to connect to, if used. Note: To view your custom domain in Salesforce, select Company Settings, My Domain. A custom domain usually ends with .my.salesforce.com.

5. For Authentication Type, select Basic Auth.
6. Under Authentication, enter the integration user's username, password, and security token.

   Note: All sensitive credentials are automatically encrypted and stored at Advanced Encryption Standard (AES)-256 encryption.

7. Select the environments to use with the connection, and click Save.
8. To test the connection, create and run a chain with the connector's List Reports command, and verify it returns a valid output.
   
   

Set up the Salesforce connector for client credentials

Client credentials authentication allows you to access Salesforce using a client ID and secret. This differs from the OAuth login method in that it does not require a scope, and you will not need to authenticate into Salesforce through the Connect button. 

Warning: This authentication method does not include a refresh token. Because of this, it is not suitable for long-running commands and may lead to timeouts in certain chains.

1. From Chain Builder, click Connections  compare_arrows, and then Create at the top right.
2. Under Connector Connection, select Salesforce and the default CloudRunner.
3. Under Basic Info, enter a unique name and description to help identify the connector.
4. Under Properties, enter the Salesforce instance or custom domain to connect to:
   

   Property	Details
   Instance	Enter the Salesforce instance to connect to. If your organization uses a custom Salesforce domain, leave blank. Note: In your Salesforce URL, the characters before salesforce.com—such as na73—represent the instance.
   Custom domain	Enter the custom Salesforce domain to connect to, if used. Note: To view your custom domain in Salesforce, select Company Settings, My Domain. A custom domain usually ends with .my.salesforce.com.

5. For Authentication Type, select Client Credentials.
6. Under Authentication, enter the client ID and secret.

   Note: All sensitive credentials are automatically encrypted and stored at AES-256 encryption.

7. Select the environments to use with the connection, and click Save.
8. To test the connection, create and run a chain with the connector's List Reports command, and verify it returns a valid output.

Troubleshooting

If the connection to Salesforce fails, you can check several configuration settings, depending on the authentication type.

OAuth2 authentication

If the connection to the Salesforce connected app fails when you first click Connect, click Stop, and wait to connect again. If the connection continues to fail using OAuth2 authentication:

• Verify the correct Salesforce instance or custom domain are entered for the connector.
• Check the client ID and secret of the Salesforce connected app the connector uses.
• In the Salesforce connected app:
  • Verify the callback URL is:
    
    • PROD - https://h.app.wdesk.com/s/wdata/oc/app/oauth/callback
    • EMEA - https://h.eu.wdesk.com/s/wdata/oc/app/oauth/callback
    • APAC - https://h.apac.wdesk.com/s/wdata/oc/app/oauth/callback
  • Ensure its selected OAuth scopes include Perform requests on your behalf at any time (refresh_token, offline_access) and at least one other scope.

If the connector loses its connection to the Salesforce app:

1. From Chains, click Connections  compare_arrows, select the connector, and click Edit.
2. Under OAuth, click Reset.
3. To enable the connector to connect to Salesforce, click Allow.
   
   

Basic authentication

If the connection fails using basic authentication:

• Verify the integration user's sign in credentials and security token. To request a new security token in Salesforce, sign in as the integration user, and select Settings, My Personal Information, and click Reset security token.
• Verify the correct Salesforce instance or custom domain are entered for the connector.
• Ensure the integration user has API Enabled permissions, in addition to permissions related to any tasks the connector performs.
  
  

Client credential authentication

If the connection fails using client credential authentication:

• Verify the correct Salesforce instance or custom domain are entered for the connector.
• Check the client ID and secret of the Salesforce connected app the connector uses.