Importing Data from Salesforce | MetaLocator Help Center

Import location records from Salesforce into MetaLocator using the Salesforce connector. You can run a single import or, if your account includes background importing, keep your location data updated on a schedule.

The connector reads Salesforce data and imports it into MetaLocator. It does not write any changes back to Salesforce.

Before you begin

You will need:

A MetaLocator account with permission to import data.
A Salesforce administrator to create an External Client App.
A Salesforce user with API access and permission to read the records and fields you want to import. This user must be able to complete Salesforce’s browser sign-in.
The name of the Salesforce object containing your data, such as Account, and the fields containing each location’s name and address.

For recurring imports, use a Salesforce user whose access will remain available for the integration. Your Salesforce administrator should confirm the app’s user-access and refresh-token policies.

This guide uses Account records and their shipping addresses as an example. Use the object and address fields that represent your actual locations.

Step 1 Create the Salesforce app

Have your Salesforce administrator complete these steps in the Salesforce organization you want to import from.

Open Setup and search for External Client App Manager in Quick Find.
Open External Client App Manager and select New External Client App. Depending on your Salesforce layout, this button may also appear in App Manager.
Enter an app name, such as MetaLocator Salesforce Import, and a contact email. Complete any other required basic fields.
Enable OAuth in the app’s OAuth settings.
Enter this Callback URL for the standard MetaLocator admin environment:

https://admin.metalocator.com/salesforceoauthcallback

The URL must match exactly, with no trailing slash.

Add both OAuth scopes:
- Manage user data via APIs (api)
- Perform requests at any time (refresh_token, offline_access)
If Salesforce displays flow settings, enable the Web Server or Authorization Code flow. Keep Require Secret for Web Server Flow enabled. MetaLocator supports PKCE, so you can keep it enabled if required by your organization.
Create or save the app.
Open the app’s Settings → OAuth Settings → Consumer Key and Secret. Complete Salesforce’s identity verification if prompted, then copy the Consumer Key and Consumer Secret for the next step. Keep the secret private.
Check the app’s Policies. If access is restricted to administrator-approved users, authorize the Salesforce user who will connect MetaLocator through the appropriate profile or permission set.

MetaLocator uses browser authorization and a refresh token for this connection. You do not need to configure the Client Credentials flow or supply a Salesforce password, security token, or WSDL file to MetaLocator.

For Salesforce’s app-management screens, see Create an External Client App. Use the MetaLocator callback URL and two scopes above; that Salesforce reference also describes settings for other integrations.

Step 2 Prepare an External Key in MetaLocator (Optional)

Use the Salesforce record’s Id column to identify the same location on future imports. This may be AccountId, Id, ContactId or similar unique identifier. This is especially helpful when creating a recurring import job. See External Key Fields for import information.

In MetaLocator, open Locations → Fields.
Select New.
Name the field Salesforce ID.
Choose External Key as the Field Type and save.

Only one External Key field can exist per table. If your location table already has one, use the existing key strategy instead of creating another field. See External Key Fields.

Step 3 Connect MetaLocator to Salesforce

Open Locations → Import.
Choose Salesforce as the data source and continue to the connection screen.
Set Connector Mode to REST.
Fill in the connection settings:

MetaLocator setting	What to enter
Connected App Client ID	The External Client App’s Consumer Key
Connected App Client Secret	The External Client App’s Consumer Secret
SalesForce Environment	Production for your live organization, or Sandbox for a test organization
SalesForce API Version	Keep the prefilled value unless your Salesforce administrator or MetaLocator Support specifies another supported version. The format is `vNN.N`, such as `v59.0`.

The fields are labeled “Connected App” in MetaLocator, but they also accept your External Client App credentials.

Click Connect to Salesforce.
On Salesforce’s sign-in page, sign in as the user authorized for the integration. Complete any required authentication and approve access if prompted.
After returning to MetaLocator, confirm that Connection Status shows Connected to: followed by your Salesforce instance.
Click Test Connection and confirm that it succeeds before selecting data.

Step 4 Choose the records and fields to import

Option 1: Use the Field Chooser

Open Field Chooser.
Choose Account from Object, or select the object containing your locations.
Choose a field from Field, then click Add.
Repeat until Selected Fields contains everything you need.

For the Account example, include:

Id
Name
ShippingStreet
ShippingCity
ShippingState
ShippingPostalCode
ShippingCountry

You can also include fields such as Phone and Website. Salesforce may display friendly field labels instead of these API names.

The Field Chooser selects fields from one object. If you need to filter which records are imported, use a custom query.

Option 2: Use a Custom Query when you need a filter

Open Custom Query and enter a Salesforce SOQL query.

This example selects Accounts with a shipping street address:

SELECT Id, Name, ShippingStreet, ShippingCity, ShippingState,ShippingPostalCode, ShippingCountry, Phone, Website FROM Account WHERE ShippingStreet != null

Click Test and review Results Preview. The preview shows up to five rows; it is not the full import. Confirm that the records represent the locations you want to publish. Ask your Salesforce administrator to adapt the query if you use custom objects, custom fields, or an eligibility field such as an active-location flag.

Use either a custom query or the Field Chooser. Clear an existing custom query before returning to the Field Chooser.

Step 5 Choose whether to keep the data updated

For a recurring import, select Keep SalesForce Data In Sync? before continuing. This option requires access to background importing and creates a job using the mapping and import options you complete next.

Leave it unchecked for a one-time import. Click Next and wait for MetaLocator to retrieve the Salesforce data.

Step 6 Match your Salesforce fields to MetaLocator

On Match Columns, check every destination field. For the Account example, use these mappings:

Salesforce field	MetaLocator destination
Id	Salesforce ID, the External Key field created earlier
Name	Name
ShippingStreet	Address
ShippingCity	City
ShippingState	State
ShippingPostalCode	Postal Code
ShippingCountry	Country
Phone	Phone
Website	Website

Map the Salesforce Id to your External Key field, not MetaLocator’s own ID field.

Map address values to the system address fields. Unmatched columns may become custom fields, which will not serve as the location’s physical address. Continue after checking the mapping.

Step 7 Choose import options and verify the results

For imports that will be repeated, select Update Existing & Insert New. With an External Key, MetaLocator can update an existing Salesforce location and add new locations.
Leave Delete Unmatched Records (Sync) off for the initial setup. Enable it only if you intend to remove MetaLocator records missing from the Salesforce result and have configured the appropriate scope.
Continue to run the import.
Review Import Summary for errors. Complete geocoding if prompted.
Open the imported locations and check their names, addresses, External Keys, and map positions.

Add can create duplicates on repeat runs when external keys are not present. Replace deletes existing destination data before importing. See Introduction to importing data for all import options.

Step 8 Enable scheduled imports

If you selected Keep SalesForce Data In Sync?:

Open Background Jobs using the processes icon in the upper-right toolbar.
Find the new Salesforce import job. New jobs are initially unpublished.
Select the job and click Force to test a background run.
Check the result and confirm that existing locations were updated without duplication.
Turn Scheduled on when the job is ready.

The default interval is every 24 hours. Contact MetaLocator Support if you need a different schedule. See Background Importing.

Changes you later make to the selected columns also require updating the job’s saved mapping through Edit Import Settings. If you reconnect Salesforce, re-save the affected scheduled import so it uses the new connection.

Salesforce SOQL Queries

MetaLocator can import fields from a single object at a time using the Field Chooser. To create more complex queries, including those with joins from multiple tables, you must author SOQL and add it to the Custom Query tab. The query must return the columns directly in the result, or as within a single relation.

An example SOQL query is provided below:

SELECT Name,ShippingStreet, ShippingCity, ShippingState, ShippingPostalCode FROM Account

This simple SOQL example pulls 5 columns from the Account object. Users commonly include filters in "WHERE" clauses to limit the data, such as in the following example which uses a custom field called "Account_Status":

SELECT Name,ShippingStreet, ShippingCity, ShippingState, ShippingPostalCode FROM Account WHERE Account_Status__c = 'Active'

Salesforce Relations and Relationship Fields

MetaLocator's data importer consumes 2-dimensional data, however; SOQL can produce multi-dimensional data sets, where a single column referenced in the query returns multiple rows as in a one-to-many relationship. In this case, the data is returned with each row in the the "one" side of the relationship repeated for every related row in the relation.

For example:

SELECT Account.Name, Id, (SELECT Contact.LastName FROM Account.Contacts) FROM Account

In this example, the related Contacts object includes multiple contacts for each Account. This causes the Account rows to repeat.

Relationship fields will be appended to end of the data set. The following query will produce the same response as the example above.

SELECT (SELECT Contact.LastName FROM Account.Contacts), Account.Name, Id FROM Account

For very complex transformations involving multiple tables and filters, SOQL may be too limited. In these cases, some customers have used tools like dataloader.io to instead create a CSV from Salesforce and then used our SFTP or CSV Import instead of connecting MetaLocator directly to Salesforce.

Troubleshooting

The connection says Not connected

Enter the app’s Client ID and Client Secret, select the correct environment, and click Connect to Salesforce. Complete the browser sign-in before using Test Connection.

Salesforce reports a callback or redirect URL mismatch

Check the app’s Callback URL character for character. For the standard MetaLocator admin environment it is https://admin.metalocator.com/salesforceoauthcallback, with no trailing slash. Dedicated environments must use their configured callback URL.

Salesforce did not return a refresh token

Add Perform requests at any time (refresh_token, offline_access) to the app’s OAuth scopes, save the change, and reconnect from MetaLocator.

Sign-in is blocked or a field is missing

Ask your Salesforce administrator to check API access, the app’s permitted-user policy, record sharing, and read access to the selected objects and fields. Confirm that you chose the intended Production or Sandbox environment.

A scheduled import reports an expired or invalid token

Reconnect with Connect to Salesforce, then re-save the affected scheduled import. Ask your Salesforce administrator to review token expiration or revocation policies if the problem returns.

The query returns no records or an error

Confirm that the object and field API names are correct and that the connected user can read the records. Review any WHERE filter with your Salesforce administrator, then use Test again.

Repeat imports create duplicate locations

Check that Salesforce Id is mapped to the External Key field and that the job uses Update Existing & Insert New. Verify that existing records have the same External Key values.

Background importing is unavailable

The sync checkbox is shown only to accounts with the required access. Contact MetaLocator Support to confirm availability for your account.

When contacting support, include the job name, selected environment, exact error message, and the time of the failed run. Do not include your Client Secret or authentication tokens.

Legacy SOAP Connections

MetaLocator supports using the SalesForce SOAP API to import data and will continue support through summer of 2027.

The below steps are for the legacy SOAP connector. Any new integrations should use the new REST connector described above

You can import location data directly from your Salesforce Account into MetaLocator. To import your data, click Data, then Import. Choose the Salesforce icon as your Data Source:

Click next to show the Salesforce Connection information. Here you must provide your Salesforce credentials to connect your account.

Once you provide a username, password and security token, click Sign In. This will load the Salesforce Objects available to your account in the Object drop-down box. To choose fields to import, choose the Salesforce object first from the Object drop-down box. That will load the list of Salesforce Fields available from that object in the Fields drop-down box. Choose a desired field and click Add to add it to the Selected Fields. Continue adding fields as needed.

You may encounter connection issues if your password contains XML-reserved characters such as

< 
>
&
"
'

Sandbox Accounts

Those requiring access to a Salesforce Sandbox Account must provide the Sandbox Partner WSDL from their SFDC account. Click the Upload WSDL file button which appears after choosing Sandbox from the Salesforce Environment drop-down as shown below:

Similarly, if a specific version of Salesforce is required for items like compound objects contact the helpdesk to have a custom version of the Partner WSDL configured in your account.

Be sure to include basic location information for your records and a field for the name. The data you choose to import should include at a minimum, Name (E.g. location name), Street Address City, State and Postal code.

Mapping Fields

Once you have either chosen fields or written a custom query, click Next, and the import process will continue as usual. Be sure to appropriately map your SalesForce columns to MetaLocator System columns as provided during the next step in the import process.

Modifying Salesforce Job and Import Mapping

Once a Salesforce import is running, you may want to modify the import rules, schedule, or query. The import is comprised of two elements, the Job and the Import Configuration.

Modify the Job Fields:

Note: updating the query will require a re-run of the job and new mappings to be applied. See the Modify the Import and Mapping blow for next steps.

Click the processes icon as shown
Select the name of the job to edit the Job fields
From there you can update the Username, Password, Token, Execution Schedule, Salesforce Query
Save the edits by clicking Save in the upper right

Modify the Import and Mapping:

Anytime a new field is added column mapping for the job will need to be re-done. Import options can also be changed from this process (E.g. Update Existing & Insert New).

Navigate to the Jobs menu in the upper right
Select the Actions dropdown for the job
Select Edit Import Settings
Update any import field mappings and select next to save the changes
On the next screen update any import options such as Update Existing & Insert New
Select Finish to save the updates

The job now has updated field mappings and options that it will use the next time it is scheduled to run.

Invalid or Incomplete Country information

Add a setting to your Salesforce job called clean_country_data with a value of 1 to invoke a process which tries to complete TLD and country data where it is provided empty.

MetaLocator looks for empty country fields with a TLD value, and sets the country name based on our internal database of country names. It only does this when the country name is not populated.

Similarly, if a country is provided, and a TLD is not provided, we look up the TLD by country name. This process should be considered a fallback. Ideally, complete country and TLD data should come directly from Salesforce.

Add a setting to your Salesforce job called correct_country_data with a value of 1 to invoke a process which tries to complete TLD and country data. This option will overwrite provided country data with MetaLocator's standard English country spelling. This can be used in the case of inconsistent data in the country field.

Changing the WSDL Version of an existing Import

When connecting to the Salesforce API, MetaLocator users can choose which Salesforce API version the connection should use. The API version is determined by the WSDL selection.

Existing background jobs may have WSDL options already set. To update an existing Salesforce background import job to a different WSDL, go to the Background jobs in the upper right: