Skip to main content
  1. Assembled
  2. Integrations
  3. Salesforce

How to connect Salesforce Service Cloud

Updated

Assembled integrates with the Salesforce Service Cloud contact platform allowing your ticket data to be forecasted and tracked in our system. This article will walk through how to setup the integration and verify the data Assembled pulls in is correct.

Preparing your Salesforce data for Assembled

Before you connect your Salesforce instance to Assembled, we recommend working with your team’s Salesforce administrator to ensure the Assembled integration user you've set up has access to the Case, AgentWork, LiveChatTranscript/MessagingSession, and CaseHistory objects.

If this is not done in advance, initial sync may fail.

Note: Assembled's sync can be customized to ignore fields on the above objects as needed.

Connecting to Salesforce

Assembled connects to Salesforce via OAuth which allows Assembled to make API requests to the Salesforce API on behalf of your Salesforce account. As a result, this will cause an overall increase in your Salesforce API usage.

Assembled will use 10,000 calls per 24 period by default, but this number can be raised or lowered upon request.

Once integrated with Assembled, if your Salesforce environment is resource constrained and encountering API limits, this may temporarily show up in Assembled as a sync invalid. If you see this error, please reach out to the Assembled Support Team for assistance tweaking the integration's API limits.

  • To connect your Salesforce instance to your Assembled instance, you will need a Salesforce admin to navigate to Assembled's Third-party integrations > Available tab and click Add from the Salesforce integration.
  • We recommend using a Salesforce Dedicated Integration User to set up the integration, rather than an individual admin user’s account.
    • These are the minimum user permissions required:
      • API REST Services and API Enabled
      • View all Case records
      • View LiveChatTranscript records
      • View UserServicePresences records
      • View Users

    • You'll want to select License = "Salesforce API integration".

      The Salesforce card in Third-party integrations with the Add button

  • If you have successfully connected to Salesforce, you will see a Synced, Sync in progress, or Connected field on the Salesforce-specific card in Assembled’s Configure > Third-party integrations page.

    Salesforce card on Configure > Third-party integrations with a Connected badge, Backfill in progress note, Manage queues, mappings, and exclusions button, and Instance (blurred), Scope and Authorized rows

If you run into any issues during this step, please reach out to our Support team.

Verifying the connection

There are two places in Assembled for you to verify if the Salesforce integration has been correctly added: the Real-time agent analysis page and the Staffing timeline.

The Real-time agent analysis page will display agent states and current adherence. Use this page to make sure agent states from Salesforce are being synced to Assembled correctly.

Monitor > Real-time agent analysis filtered to Source: Salesforce, listing agents with adherence, Salesforce source icon, state and scheduled activity (names blurred)

The Staffing timeline displays the contacts of Salesforce. Select New and reopened cases to see a line graph displaying how many tickets over time. This graph will show if the sync for tickets is working.

The Staffing timeline New and reopened cases graph with forecasted and actual lines for chat, email and phone over one day

If either of these display zero or abnormal numbers, please reach out to our Support team.

Adding agents from Salesforce

To add agents into Assembled you can follow the steps in our people page guide. Agents can be added manually or in bulk via CSV upload or through the API.

Note: If you're using Agent States, use the 18-digit Salesforce ID for your Users (To see this field in Assembled go to People management > ... > Edit > [You may need to scroll down] Salesforce ID). Do not input the 15-digit Service Cloud ID - it won't pull in the UserService Presence Statuses.

Setting up Assembled queues for Salesforce cases

To set up your Assembled queues for your new Salesforce integration, we recommend following the steps in our queue configuration guide.

In addition, please note the following Salesforce specific details:

  • Assembled will map Salesforce's origin field values to Assembled Channels as follows:
Salesforce Service Cloud Assembled
phone Phone
chat Chat
email, web Email
  • Assembled will do a containing match, not an exact match.
  • This means that by default we will exclude all other origin field values. Please reach out to our Support Team if you are using origin values not listed above.
  • For multi-channel tickets, Assembled uses the channel of the first message.
  • Any cases for which the channel field is blank will be automatically excluded from Assembled.

  • Within Assembled, you can create queues based on the following Salesforce attributes:

    Add queue rule for Salesforce dialog with the Ticket property list open: Is Deleted, Origin, Owner ID, Record Type ID, Status

Setting up Assembled agent states for Salesforce

We use UserServicePresences to sync agent states from Salesforce. In order to get agent states, you'll need to ensure you have :

To set up your Assembled agent states for your new Salesforce integration, we recommend following the steps in our agent states setup guide.

Configure > Agent states Mappings tab filtered to Platform: Salesforce and Status: Active, listing agent states with matched events, channels and queues

Understanding how Salesforce data maps to data attributes in Assembled

We track the SLA across all Channels on the Case object via the firstRespondedAt-CreatedDate metrics from Salesforce Service Cloud. If you are using a different metric for firstRespondedAt on Salesforce, please reach out to our Support team so that we can accurately parse that value from your Case object

Ticket data (Case) -- this is the object

Salesforce Service Cloud -- these are the fields Assembled
firstRespondedAt - call_started_at (Phone) OR firstRespondedAt - chat_started_at (Chat) OR firstRespondedAt - external_created_at (Email) [SLA] first_response_duration

Ticket data (LiveChatTranscript)

Salesforce Service Cloud Assembled
StartTime.Time - CreatedDate.Time (SLA) first_response_duration

Ticket status (Case)

Salesforce Service Cloud Assembled
New new
Open open
Pending pending
Solved solved
Closed closed
On Hold hold
  empty

We highly recommend only using the statuses listed above since we will only map these by default. If you are using a status not listed please reach out to the Support team to let them know.

Ticket status (LiveChatTranscript)

Salesforce Service Cloud Assembled
Completed solved
InProgress open
Waiting pending
Missed closed
Dropped closed
Blocked closed

What Assembled syncs from Salesforce

Once connected, Assembled runs these sync jobs:

Sync job What it syncs How often
backfill Historical data, up to 5 years back from when the sync job was created As fast as possible
default New and updated data Every 5 minutes
agent_states Agent states Every 30 seconds
case_histories All CaseHistory objects Every 5 minutes
live_chat_transcripts (optional) All LiveChatTranscript objects, which hold chat data Every 5 minutes
email_messages (optional) All EmailMessage objects Every 5 minutes

Assembled reads these objects through the Salesforce /v58.0/query endpoint, on the schedules above.

Salesforce allows 15,000 API requests plus 15,000 per license holder every 24 hours, up to 1,000,000. Every integration connected to your Salesforce shares this daily pool, so keep other integrations in mind when you plan your limits.

FAQs

  • Q: What should I do if I see a sync invalid from the Salesforce integration in Configure > Third-party integrations ?
    • A: This could mean a few things so we recommend hovering over the message :
      • If you see any 400 errors those usually are permissions-related. This sometimes happens when the person who originally authorized does not have proper permissions, the person who originally authorized leaves the company, or if someone changed the permissions settings. In order to continue to have data flowing into Assembled and receive accurate reporting, you will need someone with admin permissions to reauthorize the sync.
      • If you see an error message that references UserServicePresences:
        • Do you have omni-channel enabled ? If no, then that explains why you don't have userServicePresences.
        • Do you have agent states/status/presences? If no, then this could also explain it and we will disable the agent state sync.
        • Do you use a custom (or alternate) object type for agent states/status/presences? (if yes to the last question).
      • If you see a generic error please reach out to our Support Team and we can help diagnose the root cause.
  • Q: What do I do if all my tickets are getting excluded but I do not have any exclusions set up ?
    • A: The most common reason is that you are using Salesforce origin values that are not listed on this page. If that's the case, please reach out to the Support Team and we can help set up these values for you.
  • Q: What should I do if I want to create queues based on Case properties not listed in queue mapping dropdown ?
    • A: Please reach out to the Support Team and we can help set up these properties for you.

Related articles

Still have questions?