Agile ConnectLink™
This guide will walk you through troubleshooting many common ConnectLink errors and issues. Try searching this page to quickly find the information you need.
You need admin permissions to complete many of the recommended troubleshooting steps. Some changes may require input from other teams in your organization or may not be allowed by your data governance rules. Reach out to the appropriate internal resources as needed.
If you can’t find your problem on this page or the provided information doesn’t resolve it, please reach out to your Account Manager and the Integrations team for help.
Note: If your issue is about the data, use the Report a CL Data Problem button to submit discrepancies to our team. Sometimes, it’s difficult to distinguish data quality questions from integration questions. Reach out to your Account Manager if you’re not sure what the problem is, or if the Report a CL Data Problem isn’t appropriate for your needs.
This error occurs when a custom or standard Salesforce duplicate rule prevents a record from being inserted or updated. You may wish to modify or disable your duplicate rules, based on the desired behavior.
Blocking updates to existing records can lead to outdated information, inactive records incorrectly marked active, etc.
You’ll see this error when the integration tries to add or update a ConnectLink Key, but the ConnectLink Key is already assigned to another record. There are two main scenarios:
Match on Email Address
The integration attempts to match an unmatched contact by email address, but the ConnectLink Key is already assigned to another contact.
New Personnel UID
If we detect duplicate personnel in our database, we change one of them to Inactive and populate the New_Personnel_UID field with the ConnectLink Key of the primary record (also commonly referred to as the surviving record).
The integration attempts to update the deactivated person’s ConnectLink Key to the primary ConnectLink Key. If it’s already assigned to another record, the integration produces this error.
The New_Personnel_UID field is typically available for mapping to Contacts and Leads. If it’s not already mapped, add the mapping and run a Bulk Update All to populate the field. If you don’t see it in the drop-down, reach out to the Agile team. This field will help you identify these duplicates.
These errors are almost always related to State and Country/Territory Picklists. See the section below for instructions on resolving this issue.
If email fields do not allow non-Latin-based characters, such as accent marks or apostrophes, you’ll get this error message. Instructions to resolve.
The integration cannot reparent records with inactive owners. Ensure all accounts, contacts, and leads (if you use them) have an active owner.
This happens when the integration tries to populate a picklist field and the value is not in the list.
These errors occur when the maximum field length is shorter than the data the integration is trying to populate. The Agile team can provide a data dictionary containing our maximum field lengths.
These errors are most commonly seen when the integration attempts to update the Account ID for a person account.
Read the error message for details on which flow is failing and why.
Read the error message for details about which custom validation rule is causing the issue.
There are three ways to update records with Agile data:
Your field mapping preferences apply to all scheduled or on-demand Bulk Updates.
When syncing an individual record using the ConnectLink Sync button, a preview appears with the existing Salesforce value and the Agile value for each field. A checkbox indicates which data will be populated after the sync. Users can change the selection for one or multiple fields. If no changes are made, the preferences selected in the ConnectLink Setup tab will be used.
The integration can only update records with a valid ConnectLink Key.
Mapped fields are updated only for records with a ConnectLink Status of A (Active), with one exception. If the Agile Ed Null Overwrite preference is selected, the mapped email address will be updated to null for inactive personnel.
If any of the following are true, mapped fields will not be updated:
Note: Some integration-created fields will be updated for all records with a valid ConnectLink Key, including the ConnectLink Status, ConnectLink Licensed Status, and ConnectLink Last Sync Date.
The integration can only update records with a valid ConnectLink Key. Depending on the reason, there may or may not be an error.
Common reasons that the ConnectLink Key is invalid:
The ConnectLink Last Sync Date shows the last date a Salesforce record was updated by the integration. The ConnectLink Latest Update Date field contains the last date a record was updated in our database.
Here are some common reasons:
Ensure the Bulk Update All is finished. Check Apex Jobs to see if the sync has finished. All integration jobs have the Namespace Prefix ‘agileed’. You may need to change your view to see the field. Look for any failures or errors.
Errors may have prevented the record from syncing. Check the Batch Update Errors log.
Use the ConnectLink Sync button to sync the record. If there are errors, resolve them.
If there are no errors when using the ConnectLink Sync button and the record updates successfully, verify that the person who initiated the Bulk Update All has the correct permissions. They probably need the ConnectLink Admin permission set plus write access to all mapped fields.
Is the ConnectLink Do Not Update box checked? Does the ConnectLink Status equal I or U? If either of these answers is yes, see ‘Which Records are Updated’ in this section.
The record could already be up to date. To verify:
Make sure that the user who scheduled your recurring jobs is still active and has the necessary permissions.
Reach out to your account manager.
If your data license includes United States Territories and they are inactive in your picklist settings, you will get errors. Here’s a list of the territories where we have data. You can activate these options in the State and Country/Territory Picklist settings found in Salesforce setup.
| Country | Mailing State | Mailing State Full |
|---|---|---|
| United States | AS | American Samoa |
| United States | AE | Armed Forces Europe |
| United States | AP | Armed Forces Pacific |
| United States | FM | Federated States of Micronesia |
| United States | GU | Guam |
| United States | MH | Marshall Islands |
| United States | MP | Northern Mariana Islands |
| United States | PW | Palau |
| United States | PR | Puerto Rico |
| United States | VI | Virgin Islands |
Both Salesforce and Agile have multiple fields for the state/province and the country. There’s a field for the two-letter abbreviation and another for the full word. Ensure that the Salesforce and Agile fields are both the same type. See the chart below.
| Abreviation | Full Word | |
|---|---|---|
| Agile | Mailing State | Mailing State Full |
| Agile | Location State | Location State Full |
| Agile | Country Code | Country |
| Salesforce | Billing State/Province Code | Billing State/Province |
| Salesforce | Shipping State/Province Code | Shipping State/Province |
| Salesforce | Billing Country Code | Billing Country |
| Salesforce | Shipping Country Code | Shipping Country |
Occasionally, the value for the full state name in our database differs from the value in the standard Salesforce picklist. This will cause issues during syncs. To resolve these errors, you can add integration values in your picklist settings or change your mapping to use the abbreviation fields instead of the full names. The list of known mismatches is below.
| Country | Agile Full State Name | Salesforce State/Province Name |
|---|---|---|
| United States | Federated States of Micronesia | Federated Micronesia |
| United States | Virgin Islands | US Virgin Islands |
| Canada | Yukon | Yukon Territories |
Typically, this error doesn’t occur for admins, but it does occur when a different user tries to sync a record. To use the ConnectLink Sync button, the following permissions are required:
Ensure that the user receiving the error has the appropriate permissions to sync the record.
Read the error message to determine the field that’s causing the issue. Usually, this error involves the Billing State/Province or the Billing Country field. If the field is not mapped, add a mapping in the ConnectLink Setup tab. If you don’t want us to overwrite your data, choose Salesforce for the preference.
If you use State and Country/Territory picklists, see that section of this troubleshooting guide for more information about these mappings. troubleshooting
Check the Batch Update Errors section.
To submit a data problem, the ConnectLink Last Sync date must be within the last week. If it’s older than that, you’ll get this error. Use the ConnectLink Sync button to sync the record.
Note: Most of the time, records haven’t been synced in the last week, so you’ll get this error. The recommended weekly Bulk Update jobs only update records that have changed in our database since the previous sync. The only time the ConnectLink Last Sync date is updated for all ConnectLink Records is when you run a Bulk Update All.
Typically, this error occurs for normal users but not for admins. Ensure that the user receiving the error has the appropriate permissions to sync the record. To use the Report a CL Data Problem button, the following permissions are required:
Check the field mapping preference. See our Field Mappings Guide for more information.
Choose ‘Update License Data’ from the Actions Menu in the ConnectLink Setup tab. This will sync the fields with your ConnectLink order.
Ensure you’re looking at the correct object.
You cannot map multiple ConnectLink Fields to the same Salesforce field. Delete the redundant mapping.
You can map one ConnectLink field to multiple Salesforce fields. Typically, one field is set to prefer Salesforce, and the other has the AgileEd or AgileEd Null Overwrite preference.
Check for compatible data types. Otherwise, see the error message for more information.
Some dashboards, including Batch Update Errors and Record Reports, pull data directly from Salesforce. The remaining dashboards depend on the dashboard update job to display up-to-date data.
If the numbers on your dashboard seem out of date or they’re all zeros, start by clicking the refresh button in the upper-right corner. For dashboards that pull data directly from Salesforce, this will update the information. For dashboards that depend on the job, this will update the dashboard with information from the most recent job.
If refreshing the dashboard doesn’t help, check when your dashboards were last updated. Navigate to the Org Metrics dashboard and click “View Report” under the Total Institutions Number. A report will open in a new tab.
To update your dashboards immediately, go to the ConnectLink Setup tab and choose “Update Dashboards” from the Bulk Updates menu. The job may take awhile to run. You’ll get an email when the job completes.
We recommend scheduling this job to run weekly. If you don’t have any scheduled jobs, see our instructions on scheduling updates.
If the dashboard doesn’t load at all, this is likely because the owner is no longer an active user. To resolve this, change all the dashboards in the ConnectLink Dashboard folder to an active owner.
Speak with a Consultant | 866.782.0241 x 108 | [email protected]
We use cookies to ensure you get the best experience on our website. Learn more.
We’re here ready to answer your questions! Share a little information with us below and one of our Agile experts will be in touch shortly.