All customers using the Salesforce connector should move their existing import jobs to the new OAuth 2.0 connector before that date. This guide explains how to create the required Salesforce app, connect it to MetaLocator, and test a replacement import job.
Do not disable your existing Salesforce job until its replacement has been tested successfully.
Recommended migration timeline
By December 2026: Create the Salesforce app and test your replacement jobs.
By March 2027: Move your verified jobs to production.
Before June 2027: Confirm that all Salesforce jobs use the new connector and disable the legacy jobs.
Enterprise customers should complete the migration in their MetaLocator staging environment before making changes in production.
Before you begin
You will need:
A MetaLocator administrator account with access to imports and background jobs.
A Salesforce administrator who can create an External Client App or Connected App.
A Salesforce user with permission to read every object and field used by your imports.
The settings from each existing Salesforce import job, including its selected fields or custom query, field mappings, matching rules, and schedule.
We recommend creating a separate replacement job instead of changing the existing job. This allows you to test the new connector while keeping the current job available as a fallback.
Step 1: Record your existing job settings
Open each existing Salesforce import job in MetaLocator and record the following:
User information, including "Run As" and "Created by" details.
Salesforce environment: Production or Sandbox
Selected Salesforce object and fields
Custom Salesforce query, if used
MetaLocator field mappings
External key or other rule used to match existing locations
Import and update options
Categories or other data-processing rules
Current synchronization schedule
Approximate number of records normally imported
You will use these settings to create the replacement job.
Step 2: Create the Salesforce app
Sign in to Salesforce as an administrator and open Setup.
Salesforce may refer to the new app as an External Client App or a Connected App, depending on your Salesforce organization.
If External Client Apps are available
In Quick Find, search for External Client Apps.
Open External Client App Manager or External Client Apps.
Select New External Client App.
If your organization uses Connected Apps
In Quick Find, search for App Manager.
Open App Manager.
Select New Connected App.
Enter the required basic information:
App Name: MetaLocator Salesforce Connector
Contact Email: The email address of the person responsible for the integration
Complete any other required basic fields, then continue to the OAuth settings.
Step 3: Configure the OAuth settings
Enable OAuth and enter the following callback URL exactly:
https://admin.metalocator.com/salesforceoauthcallback
Do not add a trailing slash.
Add these OAuth permissions:
Manage user data via APIs
Perform requests at any time
Salesforce may display the second permission as refresh_token or offline_access.
If Salesforce presents additional OAuth options:
Enable the Web Server or Authorization Code flow.
Keep Require Secret for Web Server Flow enabled.
You may enable Proof Key for Code Exchange, also called PKCE. MetaLocator supports this option.
Save the app.
Salesforce may take several minutes to activate a newly created app or apply changes to its OAuth settings.
Step 4: Give the Salesforce user read-only access
Open the app’s policies or OAuth policies and choose who may authorize the app.
If your Salesforce organization requires administrator approval, grant the Salesforce integration user access through the appropriate profile or permission set.
The Salesforce user must have permission to read every object and field used by the MetaLocator import. Salesforce field-level security also applies to data accessed through the connector. Do not grant any object write permissions. The MetaLocator Salesforce REST connector does not support any write operations.
Under OAuth Policies, set the Refresh Token Policy to Immediately expire refresh token. For an External Client App, enable Refresh Token Rotation if Salesforce presents that setting instead. MetaLocator supports rotated refresh tokens and saves the replacement token automatically for future scheduled imports.
Unless required by your organization’s security policy, do not configure an additional idle or fixed refresh-token expiration period. If you do, the connector must be authorized again after the token expires, but this will effectively block the ability to use scheduled imports.
Step 5: Copy the Salesforce credentials
Open the app’s OAuth or consumer details and copy:
Client ID, sometimes called the Consumer Key
Client Secret, sometimes called the Consumer Secret
Keep the Client Secret private. Enter it only on the MetaLocator connector screen. Do not send it through email or include it in a support ticket.
Step 6: Open the new connector in MetaLocator
Sign in to MetaLocator as the same user that owns the current SOAP job.
Click Locations > Import.
Choose Salesforce as the data source.
Set Connector Mode to REST.
Paste the Salesforce Client ID.
Paste the Salesforce Client Secret.
Choose the appropriate Salesforce environment:
Production for a production Salesforce organization
Sandbox for a Salesforce sandbox
Leave the Salesforce API Version at its default value unless MetaLocator Support has instructed you to change it.
Step 7: Connect to Salesforce
Select Connect to Salesforce.
Salesforce will open its sign-in and approval page.
Sign in as the Salesforce user that should own the integration.
Review the requested permissions and approve access.
Salesforce will return you to MetaLocator.
Confirm that the connector displays Connected to followed by your Salesforce instance.
Select Test Connection.
Confirm that the connection test succeeds.
Step 8: Choose the Salesforce data to import
Configure the replacement job using the same method as the existing job.
Using the Field Chooser
Select the Salesforce object.
Select a field.
Select Add.
Repeat this process for every required field.
All fields selected through the Field Chooser must come from the same primary Salesforce object.
Using a Custom Query
Open the Custom Query tab.
Paste the query used by the existing job.
Select Test.
Review the preview and confirm that the expected fields and values are returned.
MetaLocator displays up to five rows in the query preview.
Step 9: Run a test import
For the first test, leave Keep Salesforce Data In Sync unchecked.
Select Next.
Review the Salesforce data returned by the connector.
Confirm that the expected columns and sample values are present.
Map each Salesforce field to the same MetaLocator field used by the existing job.
Configure the same import options and update rules.
Use the same external key or matching rule as the existing job. This is important for updating existing locations without creating duplicates.
Complete the import.
Wait for the import to finish.
Step 10: Validate the imported data
A successful job status does not necessarily mean that the migration is complete. Check the imported data before enabling automatic synchronization.
Confirm that:
The import completed without an error.
The number of records is reasonable compared with the existing job.
Existing locations were updated.
Unexpected duplicate locations were not created.
Location names, addresses, phone numbers, categories, and custom fields match Salesforce.
Records that should be excluded remain excluded.
Your locator or other customer-facing output displays the expected locations.
Enterprise customers should perform these checks in their MetaLocator staging environment first.
Step 11: Test automatic synchronization
After the manual test succeeds:
Return to the Salesforce connector.
Confirm that it still shows Connected.
Create or save the replacement job with Keep Salesforce Data In Sync enabled.
Allow at least one scheduled run to complete.
Review the job history.
Repeat the record-count and data checks from the previous step.
For important or complex imports, monitor several scheduled runs before disabling the legacy job.
Step 12: Move the job to production
Enterprise customers who tested in staging should now repeat the process in production.
Confirm that the Salesforce app allows the production MetaLocator callback URL.
Connect the production MetaLocator account to Salesforce.
Recreate the job using the settings verified in staging.
Run the job once without automatic synchronization.
Validate the imported data.
Enable automatic synchronization.
Monitor at least one scheduled production run.
A connection to a Salesforce sandbox cannot be used to access Salesforce production data. You must authorize the connector again using the appropriate production Salesforce account.
Step 13: Disable the legacy job
After the replacement job has completed successfully:
Disable automatic synchronization on the legacy SOAP job.
Confirm that only the new job remains scheduled.
Keep the old configuration available for a short observation period in case you need to compare settings.
After the observation period, remove the old job according to your organization’s normal change-management process.
Do not leave both jobs running on the same schedule. Doing so may cause duplicate or conflicting updates.
Troubleshooting
Salesforce reports a callback URL mismatch
Confirm that the app contains this exact callback URL:
https://admin.metalocator.com/salesforceoauthcallback
Check the use of https, the spelling, and the absence of a trailing slash.
The connector does not show as connected
Confirm that the Salesforce app includes:
Manage user data via APIs
Perform requests at any time
If you recently created or changed the app, wait several minutes and try connecting again.
Salesforce says the user cannot authorize the app
Ask your Salesforce administrator to grant the integration user access to the app through the required profile or permission set.
An object or field is missing
Confirm that the Salesforce user has permission to read that object and field. Salesforce object permissions and field-level security apply to the connector.
A custom query fails
Run the same query in Salesforce and confirm that:
The query is valid.
Every selected field exists.
The integration user can read every selected field.
Any filters reference valid and accessible fields.
A scheduled job stops working
Confirm that:
The Salesforce integration user is still active.
The user still has access to the required objects and fields.
The Salesforce app remains approved.
The app’s authorization has not been revoked.
Salesforce token policies have not expired the connection.
If necessary, open the connector, select Connect to Salesforce, complete authorization again, and re-save the scheduled job.
The import creates duplicate locations
Disable the new job immediately and verify that it uses the same external key and matching rules as the legacy job before running it again.
Final migration checklist
Salesforce app created
Correct callback URL entered
Required OAuth permissions enabled
Integration user granted access to the app
Integration user can read all required objects and fields
MetaLocator displays Connected
Test Connection succeeds
Replacement job uses the correct fields or query
Field mappings match the existing job
External key and matching rules have been verified
Manual test import completed successfully
Record counts and sample data were checked
Scheduled test run completed successfully
Legacy SOAP job schedule was disabled
Migration completion was documented
If you encounter a problem, contact MetaLocator Support with the job name, the approximate time of the failed run, the displayed error message, and whether the issue occurred in staging or production. Never include your Client Secret or Salesforce authorization tokens.