Troubleshooting

Cause: Salesforce hasn't fully activated the External Client App yet, or the app was just created.

Solution:

1. Wait 5–10 minutes after creating the External Client App in Salesforce
2. Return to Datatrax portal and try connecting again
3. If still failing, verify the Consumer Key and Consumer Secret are correct (copy-paste from Salesforce ECA settings)

Causes:

• Consumer Key or Consumer Secret is incorrect
• ECA not activated yet (wait 5–10 minutes)
• Using Consumer Key from wrong ECA (production vs sandbox mismatch)

Solution:

1. In Salesforce Setup, go to External Client Apps
2. Click your Datatrax ECA to open settings
3. Scroll to OAuth Settings → Consumer Key and Secret
4. Copy both values directly (don't retype)
5. Return to Datatrax portal and re-enter credentials
6. Try connecting again

Cause: The callback URL in your External Client App doesn't match Datatrax's endpoint.

Solution:

1. In Salesforce, go to Setup → External Client Apps → your ECA
2. Under OAuth Settings, check the Callback URL field
3. It should be: https://www.getdatatrax.com/auth/salesforce/callback
4. If different, click Edit and update it
5. Save and wait a few minutes for Salesforce to activate

Cause: Access token expired and automatic refresh failed (usually OAuth credential issue).

Solution:

1. Click your org in Settings → Reconnect
2. Go through the OAuth flow again to refresh credentials
3. If still failing, verify Consumer Key and Secret are still valid in Salesforce

Cause: No JWT private key uploaded yet.

Solution:

1. In Datatrax portal, go to Settings → your org → JWT credentials (action menu)
2. Paste your RSA private key in PEM format (-----BEGIN RSA PRIVATE KEY-----)
3. Click Save JWT Credentials
4. Status should update to "Configured"
5. If you don't have a private key yet, see the JWT setup guide

Cause: The key you pasted is not a valid RSA private key in PEM format.

Solution:

1. Make sure you're pasting the private key, not the certificate
2. Private key starts with: -----BEGIN RSA PRIVATE KEY-----
3. And ends with: -----END RSA PRIVATE KEY-----
4. If you lost the private key, generate a new certificate:
   • See JWT setup guide for OpenSSL commands
   • Upload the new certificate to Salesforce ECA
   • Upload new private key to Datatrax portal

Cause: The JWT audience (aud) claim doesn't match the token endpoint Salesforce expected.

Why it happens:

• Org type mismatch: Organization.org_type is wrong (e.g., marked as "production" but is sandbox)
• Instance URL doesn't match org type: Login host detection based on URL pattern fails

Solution:

1. In Datatrax portal Settings, check your org's Type column:
   • Should be "Production" for production orgs
   • Should be "Sandbox" for sandbox orgs
2. If wrong, disconnect and reconnect the org (it will auto-detect from instance URL)
3. Verify instance URL matches org type:
   • Production: https://example.salesforce.com (no .sandbox.)
   • Sandbox: https://example.sandbox.salesforce.com (has .sandbox.)
4. Try submitting the data load again

Cause: External Client App doesn't have JWT Bearer Flow enabled, or certificate not uploaded correctly.

Solution:

1. In Salesforce, go to Setup → External Client Apps → Datatrax ECA
2. Scroll to Security section
3. Check that Use digital signatures is enabled
4. Verify certificate file is uploaded (should show filename)
5. If not, click Choose File and upload your certificate (cert.pem)
6. Click Save and wait 2–5 minutes for Salesforce to activate
7. Try the data load again

Cause: Background job may be stuck or failed silently (check logs).

Solution:

1. Check Heroku logs for error messages: heroku logs -t -a your-app-name
2. Look for errors related to JWT, OAuth, or Salesforce API
3. Common issues:
   • JWT token expired: Try submitting again
   • Salesforce API limit: Wait a few minutes and retry
   • Network timeout: Check Heroku dyno status
4. If stuck for > 30 minutes, Disconnect and reconnect the org to refresh credentials

Cause: One org is using the wrong token endpoint (global env var was misconfigured, or org_type detection failed).

Solution:

1. Verify each org's Type in portal Settings:
   • Production org should show "Production"
   • Sandbox org should show "Sandbox"
2. If wrong, Disconnect and reconnect the affected org (it auto-detects from instance URL)
3. For Heroku admin: verify SF_LOGIN_HOST env var is NOT set globally
   • Check: heroku config -a your-app-name
   • If present, remove it: heroku config:unset SF_LOGIN_HOST -a your-app-name
4. Try connecting/data loading in both orgs again

Cause: Environment variable SF_LOGIN_HOST is still globally set on Heroku.

Solution:

1. SSH into Heroku or use dashboard to remove the env var: heroku config:unset SF_LOGIN_HOST -a your-app-name
2. The app now automatically derives login_host from each org's type
3. Restart the dyno: heroku dyno:restart -a your-app-name
4. Try connecting/data loading in both orgs again

Cause: Org may not be connected yet, or you're using old version of portal.

Solution:

1. Make sure org is marked as "Connected" in the Settings table
2. Verify you're on the latest version of Datatrax (v2.0+)
3. Try refreshing the page (Cmd+R or Ctrl+R)
4. If still missing, contact Datatrax support

Cause: This is normal! Private keys are encrypted at rest and not displayed in plaintext for security.

Solution:

• The key is saved securely (encrypted)
• Check the JWT status badge — should show "Configured" if valid
• If you need to replace the key, paste a new one and save again
• The plaintext never displays for security reasons

Accessing logs helps diagnose background job failures:

1. Install Heroku CLI if not already installed: brew tap heroku/brew && brew install heroku
2. Log in to Heroku: heroku login
3. View live logs: heroku logs -t -a your-app-name
4. Look for error messages related to OAuth, JWT, Salesforce API, or background jobs

Contact Datatrax support if:

• Issue persists after trying all troubleshooting steps above
• Error message is cryptic or not listed here
• Data loads are consistently failing for multiple users
• Heroku logs show internal errors (500, crash, etc.)

When contacting support, provide:

• Your Salesforce org ID (18 characters)
• Org type (Production or Sandbox)
• Specific error message from portal or Heroku logs
• Steps you've already tried