Salesforce managed package admin guide

Install the GTM Engine managed package, authorize Salesforce, verify access, and troubleshoot admin setup.

The GTM Engine managed package installs the GTM Engine External Client App into your Salesforce org so GTM Engine can securely authorize against it and read your data. This guide covers the admin steps after installing the package.

Overview

This release installs the GTM Engine External Client App, an OAuth 2.0 connected app. GTM Engine authorizes through it and reads Salesforce data over the standard Salesforce REST API, within the permissions of the user who authorized it.

There is nothing to configure in Salesforce after installation. No API key, field mapping, sync toggle, or permission set assignment is required in Salesforce. After the package is installed, connect Salesforce from GTM Engine, authorize access, then map fields in GTM Engine to start sync.

What this release does not do: the package does not push data to GTM Engine, expose working REST endpoints, make outbound callouts, or create, modify, or delete records. Two-way field-level sync, in-org configuration, and error logging are reserved for a future release.

Installation

Install from the package link:

Install the GTM Engine Salesforce managed package

Use login.salesforce.com for production and Developer Edition orgs. For a sandbox, log in to the sandbox first, then open the same link.
Choose Install for Admins Only unless instructed otherwise. End users do not need package permissions in this release.
Verify the install in Salesforce: Setup → Installed Packages should list GTMEngine, version 0.4.0, namespace gtmengine.

Installation makes no changes to your data. No post-install script runs, nothing is seeded, no records are created, and no callouts are configured.

Connect Salesforce to GTM Engine

This step happens in GTM Engine, not in Salesforce.

Log in to GTM Engine.
Open Settings → Integrations.
Click Connect on the Salesforce Managed App integration.
Log in with your Salesforce credentials when redirected to Salesforce. For a sandbox, GTM Engine must send you to the sandbox login host.
Review and approve the requested permissions on Salesforce's consent screen. The app is identified as GTM Engine.
After you return to GTM Engine, open Settings → Fields and map the required Salesforce fields in order: save Accounts, then Opportunities, then Contacts. When you map the Opportunity Forecast Category field, configure the related forecast category values underneath it. Sync starts after all three record types are saved.

For more detail on the forecast category setup, see Configure forecast categories.

Salesforce issues access and refresh tokens directly to GTM Engine, where they are stored. The managed package never receives, stores, or handles a token, and no credential is kept in Salesforce.

Choose the authorizing user

The connected app grants no access of its own. GTM Engine sees exactly what the authorizing Salesforce user can see: the same object permissions, field-level security, sharing rules, and record ownership.

Choose that user deliberately:

Match the user's access to the data GTM Engine should read. A restricted user narrows GTM Engine's visibility; a System Administrator gives it broad access.
The user needs the API Enabled permission. Without it, OAuth can succeed but API calls fail.
Prefer a dedicated integration user over a person's account. If the account is deactivated, frozen, or has its tokens revoked, the integration stops.
Keep the user's login reliable. Password expiry, MFA changes, and session-security policies all apply to the authorization flow.

To change which user GTM Engine acts as, revoke the existing authorization and reconnect as the new user.

What the connection grants

The External Client App requests four OAuth scopes:

Scope	OAuth token	What it permits
Basic	`id`	Read the Identity URL so GTM Engine learns which org and user authorized the connection.
Api	`api`	Read and write Salesforce data through the standard APIs, bounded by the authorizing user's permissions.
Web	`web`	Use an issued access token to open a Salesforce web session as the authorizing user.
RefreshToken	`refresh_token`, `offline_access`	Obtain a refresh token so the connection persists without repeated re-authorization.

Basic and Web were added in version 0.4.0; Api and RefreshToken were present in earlier versions.

A scope is a ceiling, not a grant. Nothing here gives GTM Engine visibility the authorizing user does not already have, and every request is still evaluated against that user's CRUD, field-level security, and sharing.

Harden the connection

These settings are optional, but worth reviewing against your org's standards. Open Setup → External Client App Manager → GTM Engine → Policies.

External Client Apps are managed under External Client App Manager, not the classic App Manager page.

Policy	Default as installed	What to consider
Permitted Users	All users may self-authorize	Set to Admin approved users are pre-authorized if only specific people should be able to connect the org, then grant access by profile or permission set.
IP Relaxation	Enforce IP restrictions	Leave enforced unless GTM Engine's egress addresses fall outside your trusted ranges. Add those ranges rather than relaxing the policy.
Refresh Token Policy	A fixed validity period, long-lived as shipped	Shorten it if your security policy caps integration token lifetimes. A shorter lifetime means the connection must be re-authorized more often.
Session Level	Standard	Raise to High Assurance if your org requires it for API sessions. The authorizing user must then meet that bar.

None of these changes are required for the integration to work.

Verify the connection

Two places in Salesforce confirm GTM Engine is connected and active:

Setup → Connected Apps OAuth Usage — the GTM Engine entry lists the user who authorized it, how many times the token has been used, and when it was last used. A rising use count is the clearest sign the integration is running.
Setup → Login History — filter the Application column for GTM Engine to see each OAuth login and API session.

There is nothing else to check in Salesforce. The package writes no logs of its own, and the GTM Error Log object stays empty in this release.

What else the package installs

The package carries several components that are present but do nothing in this release. They ship switched off and return to service in a future release.

Component	Behavior in this release
Apex REST endpoints under `/services/apexrest/gtmengine/`	Every method returns `null`. No permission set grants Apex class access, so no subscriber user can reach them.
`AccountTrigger`, `ContactTrigger`, `OpportunityTrigger`	Active but empty. They fire on record changes and do nothing. Saving a record is unaffected.
GTM Engine Configuration tab and page	Displays an informational notice only. No fields, buttons, or Apex.
GTM Error Log and GTM Monitored Field objects and tabs	Installed. Install for Admins Only gives the System Administrator profile full access to both objects, so an admin can open them from Setup → Object Manager. Neither packaged permission set grants anyone else access. Nothing writes to them, so they stay empty.
`GTM_Configuration__c` protected custom setting	Installed and unused. No API key or endpoint is stored.
GTM Engine Admin and GTM Engine User permission sets	Grant nothing. There is no need to assign them.
`GTMEngineAPI` remote site setting	Ships inactive on a fresh install; the package makes no callouts. See Upgrade from an earlier version if you installed an earlier version.

You do not need to assign permission sets, configure anything, or grant any access in Salesforce for the connection to work.

Upgrade from an earlier version

If the package was already installed before, some things carry over that a fresh install would not have. Item 1 applies to any upgrade; items 2 and 3 apply to orgs that ran 0.1.x or 0.2.x, the versions that still had sync logic.

Existing authorizations keep their original scopes. An OAuth token carries the scopes approved when it was issued, so a connection authorized under 0.3.0 or earlier still holds only Api and RefreshToken. To pick up Basic and Web, disconnect in GTM Engine and run Connect again.
The remote site setting is not overwritten on upgrade. GTMEngineAPI was shipped active in 0.1.x and 0.2.x, and a package upgrade leaves an existing remote site setting exactly as it is. Since this release makes no callouts, deactivate it: Setup → Remote Site Settings → GTMEngineAPI → Edit → uncheck Active → Save.
Records created by earlier versions remain. The 0.1.x post-install script seeded GTM Monitored Field rows, and the old sync path could write GTM Error Log rows. Both survive the upgrade and are unused. Delete them if you prefer a clean org; nothing reads them either way. This release declares no post-install script, so nothing is re-seeded.

Revoke, disable, or uninstall

Revoke access — go to Setup → Connected Apps OAuth Usage and revoke the GTM Engine entry. GTM Engine immediately loses API access. You can also disconnect from within GTM Engine.
Restrict who may authorize — set Permitted Users to Admin approved users are pre-authorized under connection policies.
Uninstall — go to Setup → Installed Packages → GTMEngine → Uninstall. Salesforce offers to save a copy of the package's data before removing its components. Uninstalling also removes the connected app, which permanently ends the integration.

Troubleshooting

The Connect authorization fails

Confirm the package is installed: Setup → Installed Packages should list GTMEngine 0.4.0.
Confirm the app is present: Setup → External Client App Manager, then look for GTM Engine. It will not appear under the classic App Manager page.
Check the app's Permitted Users policy. If it is set to Admin approved users are pre-authorized, the authorizing user needs access via profile or permission set.
If your org enforces IP restrictions or high-assurance sessions, confirm the authorizing user meets them.
For a sandbox, confirm GTM Engine sends you to the sandbox login host rather than production.

Authorization succeeds but every API call fails

The authorizing user most likely lacks the API Enabled permission, which some standard profiles do not include. Grant it on the user's profile or via a permission set, then reconnect.

GTM Engine cannot see records it should

The connected app grants no access of its own; GTM Engine sees exactly what the authorizing user sees. Check that user's profile, permission sets, field-level security, and sharing rules, or re-authorize with a user who has broader access.

The connection worked and then stopped

Check, in order: the authorizing user is still active and not frozen; the token was not revoked under Connected Apps OAuth Usage; the refresh token has not passed its validity period; and the user's password was not reset in an org configured to revoke tokens on password change. Any of these ends the session. Reconnect from GTM Engine.