Hansoft Perforce Integration: Streamline Your Game Dev Workflow

Troubleshooting Common Issues with Hansoft Perforce Integration

Integrating Hansoft with Perforce (P4) can greatly improve collaboration between project management and version control, but occasional issues can disrupt the workflow. This guide walks through common problems, their likely causes, and step-by-step fixes so you can restore smooth operation quickly.

1. Authentication failures (unable to connect to Perforce)

• Symptoms: Hansoft shows authentication errors when attempting to access Perforce repositories; users prompted repeatedly for credentials.
• Likely causes: Incorrect Perforce server/port, expired or revoked Perforce tickets, mismatched authentication methods (SSO vs. password), or network-level blocking.
• Fixes:
  1. Verify server/port: Confirm P4PORT in Hansoft matches Perforce server: server:port.
  2. Check credentials: Ensure Perforce username and password are correct. If using ticket-based auth, run p4 login from a client machine to refresh the ticket.
  3. SSO/LDAP: If your Perforce uses SSO or external auth, confirm Hansoft is configured to use the same method and that a service account (if used) has valid rights.
  4. Network: Test connectivity with p4 info or telnet to the P4PORT. Look for firewalls or VPN issues.
  5. Logs: Review Hansoft integration logs and Perforce server logs for specific error messages; adjust accordingly.

2. Mismatched repository paths or missing depots

• Symptoms: Hansoft cannot find files referenced in tasks or shows empty changelist mappings.
• Likely causes: Incorrect depot or branch paths in Hansoft mapping, case-sensitivity issues, or files moved/renamed in Perforce.
• Fixes:
  1. Validate mappings: In Hansoft’s Perforce integration settings, verify depot paths and branch specifiers match actual depots/streams in Perforce.
  2. Check case sensitivity: Ensure path casing matches Perforce depot (Perforce on Unix is case-sensitive).
  3. Update after renames: If files were moved/renamed, rescan or refresh Hansoft mappings so it reindexes the correct paths.
  4. Use explicit paths: Prefer using stream or full depot paths rather than relative patterns to reduce ambiguity.

3. Slow performance or timeouts

• Symptoms: Long delays when loading changelists, timeouts during sync, or sluggish Hansoft UI when fetching Perforce data.
• Likely causes: Large volumes of Perforce metadata requested, network latency, Perforce server load, or inefficient query settings.
• Fixes:
  1. Limit scope: Reduce the number of depots/branches Hansoft queries. Configure filters to only sync relevant paths or date ranges.
  2. Batch operations: Schedule heavy syncs during off-peak hours.
  3. Increase timeouts: Adjust Hansoft and Perforce client timeout settings if appropriate.
  4. Server health: Check Perforce server CPU, memory, and I/O. Resolve server-side bottlenecks or upgrade hardware.
  5. Network diagnostics: Run ping/traceroute and check for packet loss; involve network admins if necessary.

4. Missing or incorrect changelist/task linking

• Symptoms: Hansoft tasks don’t show related Perforce changelists or links point to wrong changelists.
• Likely causes: Incorrect changelist ID parsing patterns, custom commit message formats, or integration regex mismatches.
• Fixes:
  1. Verify parsing rules: Check Hansoft’s integration settings for the regex or pattern used to detect Hansoft task IDs in Perforce commit messages. Ensure it matches your commit conventions.
  2. Standardize commits: Adopt a consistent commit message format that includes the Hansoft task ID (e.g., “HANS-1234: Fix bug”).
  3. Reindex history: If links were missed historically, trigger a reindex or re-sync so Hansoft re-parses recent changelists.
  4. Handle edge cases: Update regex to tolerate prefixes, brackets, or varying separators used by developers.

5. Permission and access errors for specific users

• Symptoms: Some users can access Perforce through Hansoft while others get permission denied or see partial data.
• Likely causes: Perforce user permissions, Hansoft integration account limitations, or mapping of Hansoft users to Perforce identities.
• Fixes:
  1. Check P4 permissions: Confirm affected users have correct Perforce protections to read depots and view changelists.
  2. Service account use: If Hansoft uses a service account to access Perforce, ensure that account has wide enough permissions. Alternatively, configure per-user authentication if required.
  3. User mapping: Verify Hansoft user accounts are correctly mapped to Perforce usernames if using individual credentials.
  4. Audit logs: Review Perforce protections table and server logs to identify denied operations.

6. Incorrect file contents or sync mismatches

• Symptoms: Files opened via Hansoft show outdated or unexpected content compared to Perforce.
• Likely causes: Hansoft cache stale, client workspace mappings different, or use of pinned/reverted changelists.
• Fixes:
  1. Clear cache: Refresh or clear Hansoft’s integration cache and force a re-sync.
  2. Check workspace views: Ensure Perforce client workspaces used by Hansoft map to the correct depot paths and revisions.
  3. Verify revisions: Confirm Hansoft is requesting the intended changelist or revision; adjust settings if it’s defaulting to head or client workspace revisions.
  4. Force sync: Run p4 sync -f on a test workspace to verify server copies match expectations.

7. Integration plugin errors after upgrades

• Symptoms: After upgrading Hansoft or Perforce, integration stops working or shows API/compatibility errors.
• Likely causes: Breaking changes in APIs, deprecated calls, or configuration resets during upgrade.
• Fixes:
  1. Compatibility matrix: Check vendor documentation for supported Hansoft and Perforce versions and apply recommended plugin versions.
  2. Reconfigure: Re-enter integration credentials and settings after major upgrades to ensure none were reset.
  3. Review release notes: Look for breaking changes or migration steps required for the integration.
  4. Rollback if needed: If production is impacted, consider rolling back to the last known-good version while troubleshooting.

Diagnostic checklist (quick)

• Confirm P4PORT, P4USER, and P4CLIENT are correct.
• Test connectivity with p4 info and p4 login.
• Verify depot/stream paths and case sensitivity.
• Check parsing regex for task IDs in commit messages.
• Inspect Hansoft and Perforce server logs for errors and timestamps.
• Reduce integration scope and re-sync selectively to isolate issues.

When to contact support

• If errors persist after the above steps, collect these items before contacting Hansoft or Perforce support:
  • Hansoft integration logs and timestamps of failing operations.
  • Perforce server logs and protections table snippets.
  • Examples of failing changelists, commit messages, and affected task IDs.
  • Version numbers for Hansoft, Perforce server, and client tools.
  • Network diagnostics (ping/traceroute) showing latency or packet loss.

Following this checklist should resolve the majority of integration issues. If you want, I can generate specific commands or regex examples tailored to your repository layout—tell me your Perforce depot paths and commit message format.