Salesforce Reporting

This guide will take you through the steps to connecting Salesforce to Catalog. You can either choose to manage connections using Catalog for automatic updates(recommended) or managed by you.

info

A Salesforce System Administrator must complete these steps.

Managed by Catalog

Follow these instructions for automatic data updates.

Create a Catalog User (Optional)

We recommend creating a user and assigning them to Catalog app in order to keep a clear audit trail in Salesforce.

1. From Setup, in Quick Find, search for Users > Users.
2. Click New User.
3. For the User License choose Salesforce.
4. Set the profile to Standard User.
5. Fill in the rest of the information based on your company's administration rules.

Create Connected Client App

1. From Setup, in Quick Find, search for External Client Apps > Settings.
2. Enable Connected Apps if needed, then click New Connected App.
3. In Basic Information, enter the required information. Name the app CatalogConnector.
4. In API, check Enable OAuth.
   1. Flow Enablement
      1. Enable Device Flow
   2. Callback URL - We don’t use this, so you can enter any domain such as https://localhost.
   3. Selected OAuth Scopes:
      1. Access Lightning applications (lightning)
      2. Manage user data via APIs (api)
      3. Perform requests at any time (refresh_token, offline_access)
   4. In the same API section check the following:**
      1. Require secret for Web Server Flow
      2. Require secret for Refresh Token Flow
5. Other settings can be left at the default.
6. Click Save.

Get Connected App Client ID and Client Secret

1. From Setup, in Quick Find, search for Apps > App Manager .
2. Click on the dropdown next the app and choose View.
3. Go to API (Enable OAuth Settings) and click Manage Consumer Details.
4. Copy the Consumer Key and Secret.

Set App Permissions

For these next steps, you’ll need to clone a Permission Set.

1. From Setup, in Quick Find, search for Users > Permissions Sets.
2. Clone any permission set with the license, Salesforce. If the license doesn’t match the user assigned to the app, the connection will fail. In this example, Event Monitoring User was cloned.
3. Give your permission set a name and description.
4. Under System, click System Permissions. Then click Edit.
5. Assign the following permissions:
   1. Run Reports
   2. View Dashboards in Public Folders
   3. View Reports in Public Folders
   4. Manage All Private Reports and Dashboards
   5. View Roles and Role Hierarchy
   6. View Setup and Configuration
6. Save.
7. On the same Permission Sets page, click Manage Assignments near the top.
8. Click Add Assignment.
9. Assign the user who should have the permissions to use the Catalog app.

Permission Sets in Salesforce Setup highlighting the System Permissions section.

System permission selection in a Salesforce permission set, highlighting Manage All Private Reports and Dashboards.

Configure OAuth and OpenID Connect Settings

1. From Setup, in Quick Find, search for Identity > OAuth and OpenID Connect Settings.
2. Make sure Allow OAuth Username-Password Flows is toggled on.

Get Your Security Token

1. Make sure you’re signed in as the user who will be using the Catalog app.
2. Click on your profile, then Settings.
3. In the Quick Find, search for Reset My Security Token.
4. Click Reset Security Token.
5. You’ll get an email with the security token.

Get Your Domain and Username

warning

The username is not the same as your email. The username will look like something like this: coalesce.support.a4bb07276aff@agentforce.com.

1. From Setup, in Quick Find, search for Users > Users.

2. Find the user and click on them. Copy the information in Username.

   

3. From Setup, in Quick Find, search for Company Settings > My Domain.

4. Copy Current My Domain URL.

Connect Catalog and Salesforce

1. Go to Settings > Integrations.
2. Find and click the Salesforce tile.
3. Select Managed By Catalog.
4. Give the source a name.
5. Enter the credentials and click Save.

{
    "baseUrl": "<Your salesforce host>",
    "username": "<Your salesforce username address>",
    "password": "<Your password used to login>",
    "securityToken": "<Your security token from the reset email>",
    "clientId": "<The connected app consumer key>",
    "clientSecret": "<The connected app consumer secret>"
}

// example

{
    "baseUrl": "some-url-628db8712c-dev-ed.develop.my.salesforce.com",
    "username": "coalesce.support.a4bb07276aff@agentforce.com",
    "password": "myloginpassword",
    "securityToken": "Efe3L6BfW95xMn25bsut6lLLBxkHW",
    "clientId": "IitzUN13UdTsbHAQVr02NAVpTEMhYyQwJ",
    "clientSecret": "ENSGbqHF6QV7zTEfC3Z5VUW08"
}

info

For your first sync, it will take up to 48 hours and we will let you know when it is complete.

Troubleshooting

Check IP Restrictions

You might need to adjust your IP settings.

1. From Setup, in Quick Find, search for Connected Apps > Manage Connected Apps .
2. Click Edit next to the app.
3. Review:
   1. IP Relaxation: Enforce IP restrictions
   2. Refresh Token Policy: Refresh token is valid until revoked

Need the Client ID and Client Secret

1. From Setup, in Quick Find, search for Apps > App Manager .
2. Click on the dropdown next the app and choose View.
3. Go to API (Enable OAuth Settings) and click Manage Consumer Details.
4. Copy the Consumer Key and Secret.

How To Test Your Connection Settings

You can make an API request to check that your credentials are correct.

The request can be done using cURL and should be x-www-form-urlencoded. Using a tool such as Postman or Insomnia makes it easy.

POST

curl --location 'your-domain-url.my.salesforce.com/services/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id='consumer key' \
--data-urlencode 'client_secret=consumer secret' \
--data-urlencode 'username=coalesce.support.a4bb07276aff@agentforce.com' \
--data-urlencode 'password=this is the login password with the security token as one word. passwordsecruitytoken' \
--data-urlencode 'grant_type=password'

View Login Information

You can also check the login history to see if the connection was successful.

1. From Setup, in Quick Find, search for Users > Users.
2. Click on the Catalog user.
3. Scroll to Login History. You’re looking for the application along with the status message.

Reset Keys

• Reset the Security Key.
• The Consumer Key and Consumer Secret can't be reset. Create a new app.

Client Managed

Follow these instructions if you want to upload your own data.

Running a One-Time Extract

For your trial, you can give Coalesce a one-time view of your BI tools and upload them directly in the Coalesce App.

Running the Extraction Package

Install the PyPi Package

pip install castor-extractor[salesforce-viz]

For more details, see the castor-extractor PyPi page.

Run the PyPi Package

After the package is installed, run the following command in your terminal:

castor-extract-salesforce-viz [arguments]

Credentials

Use these arguments to provide your Salesforce credentials:

• -u, --username: Salesforce username.
• -p, --password: Salesforce password.
• -c, --client-id: Salesforce client ID.
• -s, --client-secret: Salesforce client secret.
• -t, --security-token: Salesforce security token.
• -b, --base-url: Salesforce instance URL.

Other Arguments

• -o, --output: Target folder to store the extracted files.

Getting Help

You can also run --help for a full list of arguments.

Scheduling and Pushing to Catalog

When you move out of your trial, you'll want to refresh your Salesforce Reporting content in Catalog. The Catalog team will provide you with the following:

1. Catalog Identifier: An ID to match your Salesforce files with your Catalog instance.
2. Catalog Token: An API token.

Use the castor-upload command:

castor-upload [arguments]

Arguments

• -k, --token: Token provided by Catalog.
• -s, --source_id: Account ID provided by Catalog.
• -t, --file_type: Source type to upload. Currently supported types are DBT, VIZ, and WAREHOUSE.

Target Files

To specify target files, provide one of the following:

• -f, --file_path: Push a single file.
• -d, --directory_path: Push several files at once.

Verify Directory Contents

The tool uploads all files in the given directory. Make sure the directory contains only the extracted files before pushing.

After configuring your target files, schedule the script run and the push to Catalog using your preferred scheduler to create this job.

---

What’s Next

• Error: grant type not supported

---