Category

Troubleshooting Salesforce Synchronization Errors in BoldDesk

Updated:

The Salesforce integration enables synchronization between BoldDesk tickets, contacts, Contact Groups, and corresponding Salesforce records, including cases, contacts, and accounts.

Synchronization errors can occur when required information is missing, mapped records no longer exist, authorization expires, webhook data is invalid, or repeated integration failures cause synchronization to pause. This article explains how to identify and resolve common Salesforce synchronization errors in BoldDesk.

For setup and synchronization instructions, explore more on:

  1. Installing and Configuring the Salesforce App
  2. How to Sync Tickets from BoldDesk to Salesforce
  3. How to Sync Tickets from Salesforce to BoldDesk
  4. BoldDesk Salesforce Contact and Contact Group Sync: Setup

Prerequisites

Before troubleshooting synchronization errors, ensure that:

  • The Salesforce app is installed and authorized in BoldDesk.
  • The connected Salesforce organization is active.
  • The Salesforce user used for authorization remains active.
  • The Salesforce user has access to the required accounts, contacts, and cases.
  • Salesforce synchronization is enabled for the required records and events.
  • The applicable field and status mappings are configured.
  • The BoldDesk webhook URL and API key configured in Salesforce are valid.

Identify the Synchronization Direction

Before resolving an error, determine the direction in which synchronization failed.

Synchronization Direction Examples
BoldDesk to Salesforce Creating or updating a Salesforce case from a BoldDesk ticket, or synchronizing BoldDesk contacts and Contact Groups with Salesforce
Salesforce to BoldDesk Creating or updating a BoldDesk ticket from a Salesforce case, or synchronizing Salesforce contacts and accounts with BoldDesk
Two-way synchronization Synchronizing supported changes between both platforms

The location of the failure log and the required resolution can depend on the synchronization direction.

Common Salesforce Synchronization Error Categories

Error Category Common Causes
Missing case information A required Salesforce case field is empty.
Invalid webhook data The webhook payload is empty, incomplete, or malformed.
Organization or user errors The Salesforce Organization ID is incorrect or a Salesforce user does not match a BoldDesk agent.
Record mapping errors A referenced ticket, contact, Contact Group, account, or case cannot be found.
Identity conflicts An email address is already assigned to a BoldDesk agent or contact.
Duplicate values A synchronized field requires a unique value that already exists.
Status mapping errors A Salesforce case status or BoldDesk ticket status is not mapped.
Authorization errors The Salesforce authorization expired, was revoked, or belongs to another Salesforce organization.
Paused synchronization Repeated integration job failures caused BoldDesk to pause synchronization.

Review Salesforce Failure Logs

Review the applicable failure log before retrying the operation.

Review Salesforce-Side Failure Logs

For errors that occur when Salesforce creates or updates a BoldDesk ticket:

  1. Sign in to Salesforce.
  2. Open the Salesforce App Launcher.
  3. Open BoldDesk Failure Logs.
  4. Change the list view to All Errors.
  5. Open the applicable error record.
  6. Review the error message and associated Salesforce Case ID.

If BoldDesk Failure Logs is unavailable, confirm that the affected Salesforce user has the required BoldDesk Failure Logs permission set.

Review BoldDesk-Side Failure Logs

For Salesforce integration errors recorded in BoldDesk:

  1. Go to Admin → Audit Logs.
  2. Open Integration Failure Logs.
  3. Locate the applicable Salesforce failure.
  4. Review:
    • Failed operation
    • BoldDesk record
    • Salesforce record
    • Error message
    • Failure date and time

Use the failure details to identify the applicable troubleshooting section in this article.

Resolve Missing Salesforce Case Information

A Salesforce case cannot be synchronized when a required value is missing.

Error Message Cause Resolution
Required Salesforce contact is missing. The case does not contain a supported Salesforce contact. Select a valid Salesforce contact and retry synchronization.
Required Salesforce case description is missing. The case description is empty. Enter the required case description and retry synchronization.
Required Salesforce case event type is missing. A supported case event type was not provided. Select or provide the applicable supported event type.
Required Salesforce Case ID is missing. The synchronization request does not contain a Salesforce Case ID. Confirm that the operation references an existing Salesforce case and retry it.
Required Salesforce case payload is missing. The request does not contain the required case data. Review the webhook or managed package configuration and resend the complete payload.
Required Salesforce case subject is missing. The case subject is empty. Enter a case subject and retry synchronization.

For Salesforce-to-BoldDesk ticket creation, ensure that the Salesforce case contains:

  • Subject
  • Description
  • Contact

A missing-field error does not normally require reinstalling or reauthorizing the Salesforce integration. Complete the field identified in the failure log and retry the operation.

Resolve Empty or Invalid Salesforce Webhook Data

Error Meaning Recommended Checks
Salesforce webhook payload is empty or missing. BoldDesk received no usable event data from Salesforce. Verify the webhook URL, API key, event configuration, managed package, and Salesforce automation.
Salesforce webhook payload is invalid. Salesforce sent data, but BoldDesk could not process the structure or one or more values. Verify the payload structure, required fields, Case ID, supported values, and status mappings.

Salesforce Webhook Payload Is Empty or Missing

Verify that:

  • The Salesforce managed package is installed and active.
  • The applicable ticket synchronization event is enabled.
  • The BoldDesk webhook URL is configured correctly in Salesforce.
  • The BoldDesk API key is present and valid.
  • Salesforce is sending the applicable case details.
  • The Salesforce automation or event that initiates synchronization is active.
  • The request is not blocked by Salesforce Remote Site Settings or another security configuration.

The BoldDesk webhook URL uses the following format:

https://yourbolddeskdomain/hooks/v1/salesforce

Replace yourbolddeskdomain with the actual BoldDesk domain.

Salesforce Webhook Payload Is Invalid

Verify that:

  • The payload uses the structure expected by the BoldDesk Salesforce integration.
  • All required fields are included.
  • The Salesforce Case ID is valid.
  • The BoldDesk webhook URL is correct.
  • The BoldDesk API key is valid.
  • The Salesforce case contains supported field values.
  • The selected status is configured in the applicable status mapping.
  • The request was generated by the supported Salesforce workflow.

After correcting the configuration, create or update a test Salesforce case and verify that synchronization succeeds.

Resolve Invalid Salesforce Organization or User Errors

Error Cause Resolution
Invalid Salesforce Organization ID The organization identifier does not match the Salesforce organization connected to BoldDesk. Connect the correct Salesforce organization or reauthorize the integration.
Salesforce user is not registered as a BoldDesk agent The Salesforce user does not match an active BoldDesk agent. Create or activate the matching BoldDesk agent, or assign the Salesforce record to a mapped user.

Invalid Salesforce Organization ID

To resolve the error:

  1. Confirm which Salesforce organization is authorized in BoldDesk.
  2. Sign in to that Salesforce organization.
  3. Verify that the integration is not using credentials, IDs, or records from another Salesforce organization.
  4. Reauthorize the Salesforce app if the wrong organization was connected.
  5. Retry synchronization.

Do not reuse Salesforce Organization IDs, record IDs, or credentials from another production organization or sandbox. Salesforce record identifiers belong to the organization in which the records were created.

Salesforce User Is Not Registered as a BoldDesk Agent

Use one of the following resolutions:

  • Create a BoldDesk agent using the same email address as the Salesforce user.
  • Activate the matching BoldDesk agent if the account is inactive.
  • Update the Salesforce assignment to a user whose email address matches an active BoldDesk agent.
  • Review any configured user mapping.

After correcting the user mapping, retry synchronization.

Resolve Existing Ticket Details Not Found

The Existing ticket details not found error occurs when Salesforce attempts to update a BoldDesk ticket, but the synchronized ticket reference cannot be located.

Check What to Verify
Ticket availability Confirm that the BoldDesk ticket still exists.
Deletion status Confirm that the ticket has not been permanently deleted.
Ticket reference Confirm that the Salesforce case contains the correct BoldDesk ticket reference.
Integration mapping Confirm that the synchronization mapping has not been removed or overwritten.
BoldDesk account Confirm that the case is linked to the correct BoldDesk account.
Webhook configuration Confirm that the API key and webhook belong to the expected BoldDesk account.

If the BoldDesk ticket was permanently deleted, the existing synchronization reference cannot update that ticket. Link or create the required record according to the organization’s synchronization process.

Do not replace the synchronized ticket reference with an unrelated BoldDesk ticket ID. Confirm the correct mapping before modifying the Salesforce case.

Resolve Contact and Contact Group Conflicts

Error Cause Resolution
Contact not found The referenced contact does not exist in the expected BoldDesk account or the mapping is incorrect. Verify that the contact exists and relink the correct record.
Email already used by an agent The email address is associated with a BoldDesk agent and cannot also be used for a contact. Use another email address or remove the agent association when appropriate.
Email already used by a contact The email address is associated with a BoldDesk contact and cannot also be used to create an agent. Use another email address or remove the contact association when appropriate.
Contact Group name already exists Another Contact Group already uses the submitted name. Link or update the existing Contact Group, or use a unique name.
Only one Contact Group is allowed The synchronization request contains conflicting Contact Group associations. Retain one supported Contact Group association and remove conflicting mappings.
Domain already associated with another Contact Group Another Contact Group already uses the domain. Remove the domain from the incorrect Contact Group before assigning it to the intended group.

Contact Not Found

Verify that:

  • The BoldDesk contact exists.
  • The contact has not been deleted or merged.
  • The contact belongs to the correct BoldDesk account.
  • The Salesforce contact is mapped to the correct BoldDesk contact.
  • The contact email address matches the intended record.

If the contact no longer exists, recreate or relink the contact according to the required synchronization direction.

Email Already Used by an Agent

A BoldDesk email address cannot be used for a contact when that email address is already associated with an agent.

To resolve the conflict:

  • Use a different email address for the contact.
  • Remove or change the agent’s email association when appropriate.
  • Confirm whether the individual should be represented as an agent or contact before modifying the record.

Changing or removing an agent account can affect ticket access, assignments, permissions, and historical ownership. Review the account before making changes.

Email Already Used by a Contact

This error occurs when an email address already belongs to a BoldDesk contact and synchronization attempts to use the same address for an agent.

To resolve the conflict:

  • Use a different email address for the agent.
  • Update or remove the existing contact association when appropriate.
  • Confirm whether the individual should be represented as a contact or agent.

Contact Group Name Already Exists

To resolve the error:

  1. Search for the existing Contact Group in BoldDesk.
  2. Confirm whether the existing Contact Group represents the same Salesforce account.
  3. Link or update the existing Contact Group when the records represent the same organization.
  4. Use a unique Contact Group name when the records represent different organizations.

Avoid creating duplicate Contact Groups for the same Salesforce account.

Only One Contact Group Is Allowed

To resolve the error:

  1. Review the Salesforce account associated with the contact.
  2. Review the BoldDesk Contact Group mapping.
  3. Remove conflicting or duplicate associations.
  4. Retain one supported Contact Group for the synchronized record.
  5. Retry synchronization.

Domain Already Associated with Another Contact Group

A domain can be associated with only one Contact Group in the BoldDesk account.

To resolve the error:

  1. Search BoldDesk Contact Groups for the domain.
  2. Identify the Contact Group that currently uses the domain.
  3. Confirm which Contact Group should retain the domain.
  4. Remove the domain from the incorrect Contact Group.
  5. Add the domain to the intended Contact Group.
  6. Retry synchronization.

Changing a Contact Group domain can affect automatic contact-to-group association. Review existing contacts and domain-based behavior before moving the domain.

Resolve Duplicate Field Values

The following error indicates that a field requiring a unique value already contains the submitted value:

This field value already exists.
Step Action
1 Identify the synchronized field named in the failure details.
2 Search BoldDesk and Salesforce for the existing value.
3 Determine whether the existing record should be updated instead of creating another record.
4 If the records are different, replace the submitted value with a unique value.
5 Retry synchronization.

Do not create a duplicate record merely to bypass the failure. Confirm whether the existing record represents the same contact, Contact Group, ticket, account, or Salesforce record.

Resolve Status Mapping Errors

Status mapping controls how BoldDesk ticket statuses and Salesforce case statuses are synchronized.

Review status mapping when:

  • A new Salesforce case creates a BoldDesk ticket with an unexpected status.
  • A ticket or case status update is not synchronized.
  • The failure log indicates that a status is missing or unsupported.
Synchronization Scenario Unmapped Status Behavior
Salesforce creates a BoldDesk ticket BoldDesk uses Open when the Salesforce status is not mapped.
BoldDesk creates a Salesforce case Salesforce uses New when the BoldDesk status is not mapped.
Property update The unmapped status change is skipped.

To resolve a status mapping error:

  1. Go to Admin → Marketplace → Salesforce CRM → Edit.
  2. Open the applicable ticket synchronization configuration.
  3. Review Status Mapping.
  4. Map each required BoldDesk ticket status to the applicable Salesforce case status.
  5. Save the configuration.
  6. Retry the operation using a test ticket or case.

Resolve Expired Salesforce Authorization

Salesforce authorization may expire or become invalid for the following reasons:

Possible Cause Resolution
Salesforce access token expired or was revoked Reauthorize the Salesforce integration.
Connected Salesforce user was deactivated Reactivate the user or authorize the integration using another supported administrator.
Connected user’s permissions changed Restore the required Salesforce permissions.
Salesforce password or security settings changed Complete the authorization process again.
App authorization was removed Reauthorize the Salesforce app.
Integration points to another organization Reconnect the intended Salesforce organization.

BoldDesk may send an email with a subject similar to:

Action Required: Reauthenticate Your Salesforce Integration

To reauthorize the integration:

  1. Go to Admin → Marketplace.
  2. Open the Salesforce app.
  3. Select the available authorization or reauthentication option.
  4. Sign in using an active Salesforce administrator account.
  5. Review and approve the requested permissions.
  6. Confirm that the app reconnects successfully.
  7. Review field visibility, synchronization settings, and status mappings.
  8. Retry synchronization using a test record.

Use the Salesforce organization intended for the existing integration. Authorizing another organization can cause record and organization-ID mismatches.

Resume Paused Salesforce Synchronization

BoldDesk may temporarily pause Salesforce synchronization after repeated integration job failures.

To resume synchronization:

  1. Go to Admin → Audit Logs → Integration Failure Logs.
  2. Review the latest Salesforce failures.
  3. Identify the repeated authentication, mapping, validation, record, or configuration error.
  4. Correct the underlying issue.
  5. Go to Admin → Marketplace.
  6. Open Salesforce CRM.
  7. Resume synchronization using the available control.
  8. Perform a test synchronization.
  9. Review the failure logs again to confirm that the issue is resolved.

Resolve the repeated error before resuming synchronization. If the underlying issue remains, BoldDesk may pause synchronization again after additional failures.

Resolve Generic Salesforce Processing Errors

Use the following checklist when an operation fails while creating, retrieving, or updating a Salesforce account, contact, case, or related BoldDesk record.

Check What to Verify
Failure logs Review the complete Salesforce and BoldDesk error details.
Credentials Confirm that Salesforce authorization remains valid.
Record IDs Verify that the referenced Salesforce and BoldDesk records exist.
Permissions Confirm that the connected users can access the affected records.
Required fields Verify that all required and mapped fields contain valid values.
Status mapping Confirm that the required ticket and case statuses are mapped.
Salesforce organization Confirm that the intended Salesforce organization is connected.
Webhook configuration Confirm that the webhook URL and BoldDesk API key are correct.

After completing the checks, retry the operation using a test record.

If the error continues, collect the information listed in the next section and contact BoldDesk Support.

Collect Information for Further Investigation

If synchronization continues to fail, collect the following information:

Information Details to Provide
BoldDesk account BoldDesk account URL
Synchronization direction BoldDesk to Salesforce, Salesforce to BoldDesk, or two-way
Affected BoldDesk record Ticket, contact, or Contact Group ID
Affected Salesforce record Case, contact, or account ID
Failed operation Create, update, delete, import, or another synchronization action
Error details Complete error message from the failure log
Failure time Date and time of the error, including the time zone
Synchronization settings Enabled events, synchronization type, and relevant mappings
Visual evidence Screenshot or screen recording of the failure
Recent changes Authorization, user, mapping, API key, permission, or managed package changes

Share the collected information with BoldDesk Support through the approved support channel.

Do not share Salesforce passwords, security tokens, OAuth access tokens, BoldDesk API keys, client secrets, or other confidential credentials in a support ticket, screenshot, or screen recording.

Frequently Asked Questions

  1. Where Can I Review Salesforce Synchronization Errors?
    For Salesforce-side synchronization errors:

    1. Open the Salesforce App Launcher.
    2. Open BoldDesk Failure Logs.
    3. Change the list view to All Errors.
    4. Open the applicable error.
      For BoldDesk-side errors, go to:
      Admin → Audit Logs → Integration Failure Logs
  2. Why Are BoldDesk Failure Logs Unavailable in Salesforce?
    The Salesforce user may not have the required BoldDesk Failure Logs permission set.
    In Salesforce, go to:
    Setup → Permission Sets → BoldDesk Failure Logs → Manage Assignments
    Assign the permission set to the required user.

  3. Why Does the Integration Report That a Salesforce User Is Not a BoldDesk Agent?
    The Salesforce user associated with the synchronized record does not match an active BoldDesk agent.
    Create or activate the matching BoldDesk agent using the same email address, or assign the Salesforce case to a user who already matches a BoldDesk agent.

  4. Why Does the Integration Report That Existing Ticket Details Were Not Found?
    The linked BoldDesk ticket may have been permanently deleted, the stored ticket reference may be incorrect, or the synchronization mapping may have been removed.
    Verify the BoldDesk ticket and Salesforce case references before retrying.

  5. Does Salesforce-to-BoldDesk Contact Synchronization Run Immediately?
    The initial Salesforce-to-BoldDesk contact and account synchronization may be processed as a bulk synchronization.
    After the initial synchronization, new or updated records are processed according to the configured integration behavior.

  6. Should I Reinstall the Salesforce App for Every Error?
    No. Missing fields, duplicate values, invalid mappings, and record conflicts normally require correcting the affected data or configuration. Reauthorize or reinstall the app only when the authorization, managed package, or app installation is invalid.

  7. Can the Same Email Address Be Used for a BoldDesk Agent and Contact?
    No. If the email address is already associated with an agent, the same email address cannot also be used for a contact. Similarly, an email address already used by a contact cannot be used to create an agent.

  8. Why Can a Contact Group Domain Not Be Synchronized?
    The domain may already be associated with another BoldDesk Contact Group. Locate the Contact Group currently using the domain, confirm the intended assignment, and remove the domain from the incorrect group before retrying synchronization.

Related Articles

  1. Installing and Configuring the Salesforce App
  2. How to Sync Tickets from BoldDesk to Salesforce
  3. How to Sync Tickets from Salesforce to BoldDesk
  4. BoldDesk Salesforce Contact and Contact Group Sync: Setup
Was this article useful?
Like
Dislike
Help us improve this page
Please provide feedback or comments
Comments (0)
Access denied
Access denied
Access denied
Access denied

No articles or sections found
No articles or sections found