Admin setup

Status: ⚠️ Written from the program's own install requirements, not verified against a fresh subscriber install — see What has not been verified.

Everything that has to be true before Territory Mapper works, in the order to do it.

This page exists because one of the steps below fails silently when it is missed — no error, no warning, nothing in a log. That is why it is blunt about which steps have no error message, and why the verification section at the foot is worth running even when everything looks fine.

The order

Steps 3, 4 and 5 all produce the same symptom — silence — and they have different fixes. That is what the verification section at the foot of this page is for.

1. Enable Enterprise Territory Management

Setup → Territory Settings → Enable Enterprise Territory Management.

Territory Mapper does not bring its own territory object. It uses Salesforce's own Enterprise Territory Management and adds to it, which means ETM must be on before you install.

This is a one-way switch in most orgs. If you are unsure whether it is already on, look for Territory Models in Setup — if the item is absent, ETM is off.

2. Install the package

Install from the AppExchange listing link, into a sandbox first.

Install for the profiles or users who need it. Installing for admins only means everyone else sees nothing, which reads as a broken install.

3. Enable geocoding clean rules

This has its own page, and it is the one to do carefully: Geocoding clean rules.

In short: Setup → Data Integration Rules → activate the billing address rule for each object you assign, then process existing records.

4. Configure the GIS callout credential

Territory Mapper resolves a point against boundaries by calling out to the MapKraken GIS service. The package ships that connection as a placeholder — it cannot ship a credential — so a fresh install starts with it unset.

Setup → Named Credentials → KoopGIS. Set the authorisation value MapKraken Labs supplies to you.

🔴 A missing credential fails before the request leaves your org, which means it does not appear in callout logs and does not look like a network problem. It looks like nothing happening.

Territory Mapper does report it: those records land in the exception queue as NOT_CONFIGURED, and that category exists because this is the state every new installation starts in. A queue full of NOT_CONFIGURED is the expected first sight of a new install, not a fault.

5. Grant users access to the credential

A separate step from 4, and the one most often missed.

Setting the credential is not the same as letting a user use it. On the external credential, grant access to the principal your users authenticate through — normally by assigning the relevant permission set.

Missed, this fails exactly like step 4, from the user's point of view: silence.

6. Assign permission sets

Editing a boundary, resolving an exception and assigning users all require Territory Manager. A user with only the User permission set sees the queue and cannot clear it, which is intended — but it looks like a bug if nobody said so. A viewer no longer sees the buttons for actions they cannot take.

⚠️ Known limitation — adding a user to a territory needs the Administrator set. There is no middle tier that would let, say, a sales-operations person manage territory membership without also being able to redraw boundaries. If that split matters to you, tell us: it is a small change to make and we would rather make it because a real organisation needs it than guess at the shape.

7. Allow the app's origin in CORS

Added 2026-08-13. Setup → Security → CORS → Allowed Origins List → New, and add the origin the app is served from.

The map is a web application that talks to your org directly from the browser whenever it saves. If your org has not been told to accept requests from the app's address, the browser blocks them before they are sent, and the failure looks like this:

Error creating territory: Failed to fetch

Nothing is wrong with your data, your credential or your permission sets when you see that — the map will have loaded normally, and reading works. Only saving fails, and it fails for every write: creating a territory, renaming one, editing the model.

Two rules the platform enforces, both of which catch people out:

• The origin must be https://. Salesforce rejects an http:// entry outright, with "Invalid protocol in a URL pattern. Origins must use the HTTPS protocol."
• The origin is scheme + host + port, with no trailing path.

If you are unsure what to enter, open the map, then open your browser's developer console on a failed save — the blocked origin is named in the error.

8. Define your territory roles

Added 2026-08-18. Setup → Custom Metadata Types → Territory Role → Manage Records.

The package ships no roles. That is deliberate — a territory role is your organisation's vocabulary, and inheriting someone else's org chart would be worse than starting empty. Until you add some, the role selector has nothing to offer and users cannot be added to territories.

These are not the roles under Setup → Users → Roles. That is your sharing hierarchy and it has nothing to do with this. See Roles and assignment.

Add each role

Flat, hierarchical, or both

Parent Role API Name is the only field that decides the shape. Leave it blank on every role and you get a flat list. Fill it in and you get trees. Mix them freely — there is no setting to switch between the two, and no limit on how many trees you have.

Sales                        ← blank parent, Is Assignable unticked
  Sales Manager
    Sales Rep
Operations                   ← blank parent, a second tree
  Dispatcher
Contractor                   ← blank parent, no children: a flat role

Territory Model Name — leave it blank

Blank means the role applies to every territory model you load, which is what almost everyone wants. It also means your roles survive cloning a territory model, which is how territory realignment normally works — a per-model role set would have to be re-created on every planning cycle.

Fill it in (with a model's Developer Name) only when one model genuinely needs a different set of roles. A model-specific set replaces the org-wide one for that model rather than adding to it.

Grouping roles (optional)

Setup → Custom Metadata Types → Functional Group → Manage Records adds groups — Sales, Operations, or however your business divides up. Set Functional Group on each role to place it.

Groups are entirely optional. If you define none, the group selector does not appear and nothing is lost.

If you want clean reporting on Role in Territory

The role is stored on the standard Role in Territory field of the user-territory association. That field is a Salesforce picklist with its own separate value set, and it does not learn your role names automatically.

Everything works without doing anything about this — the field accepts your values as they are. But **reports and list views that filter on Role in Territory will not offer your role names as choices. If you need that, mirror them into Setup → Picklist Value Sets → RoleInTerritory2**.

🔴 Do not tick "restrict to defined values" on that picklist unless you have mirrored every role name first. If you do, every attempt to assign a user fails. The app will tell you exactly that when it happens, but it is easier not to hit it.

Verify the whole chain

Run these in order. Each one separates two different failures, so do not skip ahead — a later check is only meaningful once the earlier one passes.

1. Do records have coordinates?

SELECT BillingGeocodeAccuracy, COUNT(Id) FROM Account GROUP BY BillingGeocodeAccuracy

All null → step 3. Full reading of this result.

2. Did anything get assigned?

SELECT COUNT(Id) FROM ObjectTerritory2Association

Zero, while check 1 shows coordinates → the geocode half is fine and the callout half is not. Go to 3.

3. What does the exception queue say?

Open Assignment Exceptions and look at the categories:

After fixing anything: select the affected rows and choose Re-run after a fix. Fixing the cause does not, by itself, retry the records that already failed for it.

What has not been verified

Stated so that nobody reads this page as a tested procedure.

These steps are drawn from the program's install requirements and from an org where Territory Mapper is already running. They have not been walked through end to end on a fresh subscriber org, because no validated package build exists yet to install into one — and install-time behaviour cannot be verified in the integration org, which is a Developer Edition org already carrying the app.

What that means in practice: the set of steps is right — each one is a value the package ships as a placeholder and cannot ship as a value. What is unverified is the exact wording of screens, and whether a genuinely fresh org needs anything not listed here. If you hit a step that is not on this page, tell MapKraken Labs — it is a documentation defect, and this is the page that gets it.