Setting up Salesforce

This article will guide you through the process of connecting your Spekit instance to Salesforce. The Salesforce integration allows you to import important objects, fields, and other metadata into Spekit to help you create documentation and training.

Completing this process requires the collaboration of a Salesforce Administrator and a Spekit Administrator.

Step 1: Meet the Prerequisites (For your Salesforce Admin)

The Salesforce integration allows you to select objects important to your company's process flow to import into Spekit. Before proceeding, you must complete the following prerequisites:

Create a Salesforce integration user.

Before connecting, you must ensure your Salesforce integration user has the following permissions and settings. If you do not have an integration user, one should be created for this process.

Required Salesforce Profile Permissions:

• Modify Metadata Through Metadata API Functions
• API Enabled
• No IP restrictions (Optional, but recommended for uninterrupted syncing)

Note on User Syncing: If you intend to sync Salesforce users to Spekit and your Salesforce Organization has "Profile Filtering" enabled, you must also enable the "View All Profiles" option on the integration user's profile to allow proper Salesforce user syncing.

• Salesforce Help Article: https://help.salesforce.com/s/articleView?id=release-notes.rn_forcecom_profiles_perms_profile_filtering.htm&release=228&type=5

Step 2: Connect from the Spekit Web App (For your Spekit Admin)

After the prerequisites are complete, a Spekit admin can initiate the connection from within Spekit. This step will make the Spekit OAuth app available in Salesforce for installation.

1. From the Spekit Web App, click Settings.
2. Click Connect.
3. Click Connect to Salesforce.
4. Add a check to the checkbox for Sync User's profiles to import the list of people who are users in Salesforce and can be invited to Spekit.
   • Leave this unchecked if you are connecting an IDP (Okta, OneLogin, Azure, etc.) with SCIM 2.0.
5. Add a check to the checkbox to confirm: I have the required Salesforce permissions.
6. Click Connect a Salesforce Production or Developer Org.
7. You’ll be redirected to log in to Salesforce. Enter your Spekit Integration Salesforce Username and Password.
8. Click Log In.
   • Note: If your company uses a custom domain (e.g., https://somethingcool.my.salesforce.com), click the Use Custom Domain link in the bottom right, enter your custom domain (e.g., somethingcool), and click Continue.
9. A pop-up will prompt you to Allow Access for the Spekit OAuth, which gives Spekit the ability to connect to Salesforce. Click Allow.
10. Allow the initial Salesforce sync to complete before navigating away from the page. This may take a few minutes.

When the initial sync is complete, you will receive a confirmation email from Spekit.

 

Step 3: Install the Spekit OAuth App in Salesforce (For your Salesforce Admin)

This step is critical for securely connecting Spekit with your Salesforce instance and preventing common permission errors. A Salesforce administrator must complete this step after the previous step has been performed.

1. Log in to Salesforce and Open Setup
   • Click the gear icon ⚙️ in the upper-right corner.
   • Select Setup from the dropdown menu.
2. Navigate to Connected Apps
   • In the Quick Find search bar (on the left-hand side), type Connected Apps.
   • From the search results, click Connected Apps OAuth Usage.
3. Locate and Install the Spekit OAuth App
   • In the list of connected apps, find Spekit OAuth.
   • Click the Install action on the right side of the page.
   • Follow the prompts to complete the installation.

Once the OAuth app is installed for your organization, the Spekit administrator can proceed with the connection.

What are the limitations of connecting Spekit to Sandbox?

You can connect Spekit with your Sandbox, but there are some limitations:

• Each Spekit account can only be connected to ONE Salesforce org at a time (sandbox, production, or free developer).
• You can test with as many sandboxes as you want - simply create a new Spekit account to connect to the sandbox.
• However, for the ONGOING use case, we highly encourage connecting and maintaining documentation in your Salesforce production org. Spekit does NOT support Salesforce sandbox refreshes, doing so will break the integration connection since the Salesforce org and user IDs will change.
• We can transfer content on your behalf from any sandbox account to production when you're ready.

Does Spekit maintain any version control system for my metadata?

While we should not be viewed as a system of metadata backup, we do store the most logs on specific changes made directly in Spekit.

Spekit tracks the following:

• Last Edited On in Spekit
• Last Edited By in Spekit

We also pull and display the following from the Salesforce Spekit Admin reference, though not as a log:

• Last Synced from SFDC (last date only)

How often is the Salesforce metadata we imported into Spekit updated?

As an Admin, you can re-sync metadata from your Salesforce org anytime by going to the Settings > Accounts section and clicking Sync now. You may be asked to re-authenticate your org by logging into Salesforce.

How to enable "Modify Metadata Through Metadata API Functions" permission

If you are a Salesforce System Administrator, this permission is automatically enabled for your profile.

The Modify Metadata Through Metadata API Functions permission is enabled at the Profile level for the Salesforce user. To check for the Modify Metadata permission, follow these steps in your Salesforce org:

• Click the gear icon (upper right corner).
• From the drop-down, click Setup.
• Under the Administration header, click Users > Profiles.
• Locate and click on the Profile that is associated with the Salesforce user.
• From the Profile view, click System Permissions.
• Click Edit.
• Scroll down to the Modify Metadata Through Metadata API Functions field and add a check to the checkbox ☑
• Click Save.

How to enable the "API Enabled permission"

If you are a Salesforce System Administrator, this permission is automatically enabled for your profile. 

Note: Some editions of Salesforce do not have API access.

This Salesforce help article shows the Salesforce editions with API access https://help.salesforce.com/HTViewSolution?id=000005140

The API Enabled permission is enabled at the Profile level for the Salesforce user. To check for the API Enabled permission, follow these steps in your Salesforce org:

• Click the gear icon (upper right corner).
• From the drop-down, click Setup.
• Under the Administration header, click Users > Profiles.
• Locate and click on the Profile that is associated with the Salesforce user.
• From the Profile view, click System Permissions.
• Click Edit.
• Scroll down to the API Enabled field and add a check to the checkbox ☑
• Click Save.

How much of our Salesforce API limits does Spekit use?

• Spekit does not automatically run the Sync now process in the Spekit Web App.
• The Sync now the process is 100% manually triggered.
• Only run the Sync now process when changes have been made in the Salesforce org connected with the Spekit instance you want to pull in.

As a rough benchmark, 12 imported objects = 170 API calls per sync.

If you have a lot of installed package fields on standard objects and very "crowded" objects, this can be higher.

For larger organizations, we've found this to be around ~400 at the upper end, but since every implementation is different, it will vary.

We recommend  you to test for yourself by connecting a sandbox org and checking the System Overview in Salesforce (Setup > System Overview) after running a sync.

Example: System Overview showed 16 API calls used in the last 24 hours.

Run the Sync now process to pull updates for twenty Salesforce objects that have been imported. System Overview API Usage before running Sync now.

System Overview API Usage after running Sync now. 

The Sync process consumes a total of 341 API calls.