# Salesforce

{% hint style="info" %}
**Important:** The Salesforce integration is currently available by request. Contact our Customer success team to enable this feature for your organization.
{% endhint %}

## Overview

The Instruqt Salesforce integration enables your sales team to:

* **Create personalized invites** directly from Opportunity records
* **Track prospect engagement** including time spent, progress, and completion
* **View session feedback** and ratings within Salesforce
* **Match activity to Contacts** automatically by email address

## **How It Works**

When a user creates an invite from an Opportunity in SalesForce, Instruqt generates a shareable link. When prospects claim the invite and complete tracks, their activity syncs back to Salesforce as Session records - giving your team visibility into engagement without leaving the CRM.

### **Prerequisites**

Before enabling the integration, ensure you have:

| Requirement | Instruqt                 | Salesforce                             |
| ----------- | ------------------------ | -------------------------------------- |
| **Role**    | Team Owner or Team Admin | System Administrator                   |
| **Edition** | Any paid plan            | Professional, Enterprise, or Unlimited |

{% hint style="warning" %}
**Lightning Experience Required:** This integration uses Lightning Web Components and is not compatible with Salesforce Classic.
{% endhint %}

## **Enable the Integration**

The setup requires configuration in both Instruqt and Salesforce. Watch [the video](https://youtu.be/LNbGnYz_tzI?si=YAG6EIPfCw6ZwlS1), and follow these 4 steps in order.

#### **Step 1: Get the Installation Link from Instruqt**

1. Log in to [play.instruqt.com](https://play.instruqt.com/) as a Team Owner or Admin
2. Navigate to **Team Settings > Integrations**
3. Find the **Salesforce** card and click **Connect**
4. You'll receive a **package installation link**
5. Click the link to proceed, or copy it to share with your Salesforce admin

> The link takes you to Salesforce to install the managed package.

#### **Step 2: Install and Configure in Salesforce**

#### **2a. Install the Managed Package**

1. Click the installation link from Instruqt (or paste it into your browser)
2. Log in to Salesforce as a System Administrator
3. Choose **Install for All Users** (recommended)
4. Click **Install** (installation can take a a few minutes, you will recieve an email when complete)
5. Wait for the installation confirmation email

> Verify: Go to **Setup > Installed Packages** and confirm "Instruqt for Salesforce" appears.

#### **2b. Assign the Integration Permission Set**

{% hint style="warning" %}
**Complete this step BEFORE returning to Instruqt.** Without this permission set, data sync will fail.
{% endhint %}

1. Go to **Setup > Users > Permission Sets**
2. Click **instruqtapp\_\_Integration\_Access**
3. Click **Manage Assignments > Add Assignment**
4. Select the user who will complete the OAuth connection. That user will finish the integration process from Instruqt in Step 3. (see tip below)
5. Click **Assign**

{% hint style="info" %}
**Recommended:** Create a dedicated integration user (e.g., \`<instruqt-integration@yourcompany.com>\`) for the OAuth connection. This ensures the integration stays connected even if individual users leave your organization.
{% endhint %}

#### **2c. Activate Remote Site Setting**

{% hint style="danger" %}
**Critical:** Salesforce installs Remote Site Settings as **inactive** by default. You must manually activate this setting or API calls will fail.
{% endhint %}

1. Go to **Setup > Security > Remote Site Settings**
2. Find **Instruqt\_API** (or `instruqtapp__Instruqt_API`)
3. Click **Edit**
4. Check the **Active** checkbox
5. Click **Save**

***

#### **Step 3: Complete the Connection in Instruqt**

{% hint style="warning" %}
**Log in as the correct user.** During the OAuth flow, you must authenticate as the Salesforce user who has the \`instruqtapp\_\_Integration\_Access\` permission set assigned.
{% endhint %}

1. Return to Instruqt and click **Continue**
2. You'll be redirected to Salesforce for OAuth authorization
3. **Log in using the Integration User credentials** (the user with `instruqtapp__Integration_Access`)
4. Review the requested permissions and click **Allow**

> Verify: The integration card in Instruqt shows **"Connected"** status.

{% hint style="info" %}
**Data Processing:** Instruqt uses Paragon as a subprocessor to handle Salesforce data synchronization. See our subprocessors [list](https://instruqt.com/legal/subprocessors) for details.
{% endhint %}

***

#### **Step 4: Assign User Permission Sets in SalesForce**

Grant access to your sales team based on their role:

| Role                  | Permission Set        | Access                              |
| --------------------- | --------------------- | ----------------------------------- |
| Sales Representatives | `instruqtapp__Editor` | Create invites, view sessions       |
| Sales Managers        | `instruqtapp__Viewer` | Read-only access to all data        |
| Salesforce Admins     | `instruqtapp__Admin`  | Full access including configuration |

**To assign a permission set:**

1. Go to **Setup > Users > Permission Sets**
2. Click the appropriate permission set
3. Click **Manage Assignments > Add Assignment**
4. Select users and click **Assign**

**That's it!** The integration is now active. Instruqt data will sync to Salesforce automatically.

***

### **Recommended Configuration**

The following configurations are optional but recommended for the best experience.

{% tabs %}
{% tab title="Page Layout" %}

#### **Add the Quick Action to Opportunities**

Enable the "Create Instruqt Invite" button on Opportunity records:

1. Go to **Setup > Object Manager > Opportunity > Page Layouts**
2. Edit your active Opportunity layout
3. In the palette, find **Mobile & Lightning Actions**
4. Drag **Create Instruqt Invite** to the "Salesforce Mobile and Lightning Experience Actions" section
5. Click **Save**

> Verify: Open any Opportunity and confirm the action appears in the highlights panel.

***

#### **Add Related Lists (Recommended)**

Display Instruqt data directly on Opportunity records:

1. Edit your Opportunity page layout
2. Scroll to the **Related Lists** section
3. Add these related lists:
   * **Instruqt Invites** — Invites created for this Opportunity
   * **Instruqt Sessions** — Prospect activity and progress
4. Click **Save**

**Recommended columns for Instruqt Invites:**

* Title, Status, Invite URL, Claim Count, Expires At

**Recommended columns for Instruqt Sessions:**

* Contact, Content Title, Status, Progress, Completed At, Rating
  {% endtab %}

{% tab title="Reports" %}

#### **Share Reports with Your Team**

The package includes 5 pre-built reports in the **Instruqt\_Reports** folder:

| Report                     | Description                                   |
| -------------------------- | --------------------------------------------- |
| Engagement by Opportunity  | Which prospects engaged with hands-on content |
| Pipeline by Stage          | Pipeline view with engagement per stage       |
| Completion Analysis        | Completion rates across all invites           |
| Content Engagement Summary | Which content drives the most engagement      |
| All Opportunities Pipeline | Pipeline overview with Instruqt activity      |

**To share reports:**

1. Go to **Reports > All Folders > Instruqt\_Reports**
2. Click the folder dropdown > **Share**
3. Add appropriate users, roles, or public groups
4. Set access level (View or Edit)
   {% endtab %}
   {% endtabs %}

***

## **Using the Integration**

You can watch video on how to use Instruqt's SalesForce integration [here](https://youtu.be/Q8Ia9lzwhiE?si=7fn8LOctcSLq3Vsg).

### **Create an Invite from an Opportunity**

1. Open an Opportunity record in Salesforce
2. Click **Create Instruqt Invite** in the highlights panel (or from the actions dropdown)
3. **Step 1 - Initial configuration of the Invite:**
   1. **Details:** Public Title (required), Public Description, Internal Title
   * **Sharing:** Sharing Method (Shareable Link or Embed), Invite Type (Self-Paced or Live Event)
4. **Step 2 - Select Content:**
   * Browse or search available tracks and labs
   * Click **Add** to select content for the invite
   * Use **Refresh** to sync the latest content from Instruqt
   * Click **Next** when done
5. **Step 3 - Configure limits of the invite:**
   * **Access Mode:** Anyone with the link, Anyone leaving the details, (recommended) Only specific people
   * **Limits:** Invite Limit, Expiration, Play Limit, Play Time Limit
   * **Settings:** Learner Sharing, Instructor Tools, Screen Sharing
6. **Step 4 - Select Contacts (will be skipped if you selected Anonymous is Step 3):**
   * Select contacts from the Opportunity to receive the invite
   * Leave all unchecked for an anonymous invite link
   * Click **Next** to continue
7. Click **Create Invite**

> The invite URL appears on the Instruqt Invite record. Share this link with your prospects.

### **Track Prospect Engagement**

When prospects claim an invite and start a track:

1. An **Instruqt Session** record is created in Salesforce
2. The session automatically links to:
   * The **Contact** (matched by email)
   * The **Opportunity** (from the invite)
   * The **Invite** used to access the content
3. Progress updates sync as the prospect completes challenges

**Session fields include:**

* **Status:** Not started, In progress, Completed
* **Progress:** Visual summary of challenge completion (e.g., ✓ ✓ ○ ○)
* **Duration:** Time spent in the track
* **Rating:** Prospect's rating (1-5 stars)
* **Feedback:** Written comments from the prospect

{% hint style="info" %}
**Sync Timing**: Session data typically syncs within 2-30 seconds of activity in Instruqt.
{% endhint %}

***

## How to Use Instruqt's Reports in Salesforce

The Instruqt for Salesforce package includes 5 pre-built reports to help you measure the impact of hands-on experiences on your sales pipeline.

{% embed url="<https://youtu.be/mNi7bsRb7oQ?si=BNKPr5xz6S4CLWft>" %}

### Available Reports

#### Engagement by Opportunity

Identifies which prospects have actively engaged with your hands-on content.

**Use this report to:**

* See which contacts on a deal have completed labs or demos
* Prioritize follow-ups with engaged buyers
* Identify opportunities where prospects haven't engaged yet

***

#### Pipeline by Stage

Shows your sales pipeline with Instruqt engagement metrics broken down by deal stage.

**Use this report to:**

* Understand how engagement correlates with deal progression
* Identify stalled deals lacking hands-on engagement
* Track engagement trends across your pipeline stages

***

#### Completion Analysis

Measures completion rates across all invites you've sent.

**Use this report to:**

* Identify content that prospects finish vs. abandon
* Spot content that may be too long or complex
* Optimize your hands-on experiences based on completion data

***

#### Content Engagement Summary

Reveals which specific tracks, labs, and sandboxes drive the most engagement.

**Use this report to:**

* Double down on high-performing content
* Identify underperforming assets that need improvement
* Align sales and marketing on which content resonates

***

#### All Opportunities Pipeline

Provides a holistic pipeline view combining deal data with Instruqt activity.

**Use this report to:**

* Get a single view of deal health and prospect engagement
* Support pipeline reviews and forecasting
* Identify opportunities that could benefit from hands-on content

***

### Accessing Reports

All reports are located in the **Instruqt\_Reports** folder:

1. Go to **Reports** in Salesforce
2. Navigate to **All Folders > Instruqt\_Reports**
3. Click any report to view it

***

### Sharing Reports with Your Team

To give your sales team access to these reports:

1. Go to **Reports > All Folders > Instruqt\_Reports**
2. Click the folder dropdown and select **Share**
3. Add appropriate users, roles, or public groups
4. Set access level:
   * **View** — Users can run reports but not modify them
   * **Edit** — Users can customize and save report changes
5. Click **Save**

{% hint style="info" %}
**Tip:** Share with a public group like "Sales Team" rather than individual users for easier maintenance.
{% endhint %}

***

### Customizing Reports

You can modify any pre-built report to fit your needs:

1. Open the report you want to customize
2. Click **Edit**
3. Add or remove fields, filters, and groupings
4. Click **Save As** to create your own version

{% hint style="warning" %}
**Note:** Save customizations as a new report to preserve the original pre-built version.
{% endhint %}

***

### Building Custom Reports

To create your own Instruqt reports:

1. Go to **Reports > New Report**
2. Select a report type:
   * **Instruqt Invites** — Report on invite creation and usage
   * **Instruqt Sessions** — Report on prospect engagement and progress
   * **Instruqt Invites with Sessions** — Combined view of invites and resulting activity
3. Add fields, filters, and groupings as needed
4. Save to the **Instruqt\_Reports** folder or your own folder

**Useful fields for custom reports:**

| Object           | Key Fields                                                               |
| ---------------- | ------------------------------------------------------------------------ |
| Instruqt Invite  | Title, Status, Claim Count, Expires At, Opportunity                      |
| Instruqt Session | Contact, Content Title, Status, Progress, Duration, Rating, Completed At |

***

## **Architecture**

#### **Data Model**

The integration creates custom objects in Salesforce to store Instruqt data. All objects use the `instruqtapp__` namespace prefix:

| Object                         | Purpose                               | Relationship                            |
| ------------------------------ | ------------------------------------- | --------------------------------------- |
| `instruqtapp__Config__c`       | Stores API credentials and sync state | 1 per org                               |
| `instruqtapp__Content__c`      | Caches track/lab metadata             | —                                       |
| `instruqtapp__Invite__c`       | Invite records                        | Lookup to Opportunity                   |
| `instruqtapp__Invite_Claim__c` | Records when invites are claimed      | Master-Detail to Invite                 |
| `instruqtapp__Session__c`      | User progress and engagement          | Lookups to Contact, Opportunity, Invite |

#### **Authentication**

| Direction             | Method                                                      |
| --------------------- | ----------------------------------------------------------- |
| Salesforce → Instruqt | KMS-signed JWT (API Key stored in `instruqtapp__Config__c`) |
| Instruqt → Salesforce | OAuth 2.0 (managed by Paragon)                              |

***

### **Troubleshooting**

{% tabs %}
{% tab title="Connection Issues" %}

#### **OAuth connection fails**

**Symptoms:** Error during Salesforce login or redirect fails

**Solutions:**

1. Clear browser cache and cookies
2. Use an incognito/private browser window
3. Ensure you're logging in with the user who has `instruqtapp__Integration_Access`
4. Verify the Remote Site Setting is **active**

***

#### **Integration shows "Disconnected"**

**Symptoms:** Previously working integration stops syncing

**Solutions:**

1. The Integration User may have been deactivated—verify user is active
2. OAuth token may have expired—reconnect the integration from Instruqt
3. Check Remote Site Setting is still active in Salesforce Setup

***

#### **Package installation fails with Apex compile errors**

**Symptoms:** The package installation fails with errors like "Invalid type" or "Method does not exist", referencing classes that are not part of the Instruqt package.

**Solutions:**

1. Check the class names in the error messages — Instruqt package classes all have the `instruqtapp__` prefix. If the failing classes don't have this prefix, they belong to your org.
2. Fix the broken classes in your org by updating method signatures or references to match current code.
3. Delete any broken classes that are no longer needed (e.g., old test classes or deprecated schedulers).
4. Retry the package installation once your org compiles cleanly.

{% hint style="info" %}
Salesforce recompiles all Apex code in the org during package installation. If your org has pre-existing broken code, this surfaces those errors even though they existed before the install. The Instruqt package has no triggers on standard objects and no batch or scheduler classes.
{% endhint %}
{% endtab %}

{% tab title="API Errors" %}

#### **"Unauthorized endpoint" error**

**Symptoms:** Invite creation fails, tracks don't load, or sync fails

**Solutions:**

1. Go to **Setup > Security > Remote Site Settings**
2. Find the **Instruqt\_API** entry
3. Click **Edit** and ensure **Active** is checked
4. Save and retry

{% hint style="danger" %}
This is the most common issue. Salesforce installs Remote Site Settings as inactive by default.
{% endhint %}

***

#### **"Unable to fetch tracks" error**

**Symptoms:** Invite wizard shows error when loading content

**Solutions:**

1. Verify integration shows "Connected" in Instruqt
2. Check Remote Site Setting is **active** for `api.instruqt.com`
3. Verify `instruqtapp__Config__c` record has valid Team ID and API Key
   {% endtab %}

{% tab title="Data Issues" %}

#### **Sessions not appearing**

**Symptoms:** Prospects complete tracks but no Session records appear

**Solutions:**

1. Wait up to 5 minutes for real-time sync to complete
2. Verify the prospect used the correct invite link
3. Check the Integration User has `instruqtapp__Integration_Access`
4. Run a retroactive sync to backfill missing data

***

#### **"Create Instruqt Invite" button not visible**

**Symptoms:** Users don't see the button on Opportunities

**Solutions:**

1. Verify Quick Action is on the Opportunity page layout
2. Confirm user has `instruqtapp__Editor` or `instruqtapp__Admin` permission set

***

#### **Users can't see Instruqt objects**

**Symptoms:** Tabs or related lists don't appear

**Solutions:**

1. Verify user is assigned an Instruqt permission set (Viewer, Editor, or Admin)
2. User may need to log out and back in after assignment
3. Check profile-level object permissions if using custom profiles
   {% endtab %}
   {% endtabs %}

***

### **Verification Checklist**

After setup, verify the integration is working:

**Connection:**

* [ ] Remote Site Setting for `api.instruqt.com` is **active**
* [ ] Integration shows "Connected" in Instruqt Team Settings
* [ ] `instruqtapp__Config__c` record exists in Salesforce

**Functionality:**

* [ ] Users can see "Create Instruqt Invite" button on Opportunities
* [ ] Invite wizard loads tracks/labs successfully
* [ ] Creating an invite returns a working URL
* [ ] Claiming an invite creates a Session record in Salesforce
* [ ] Session progress updates as challenges are completed