<!– SEO Title: TeamPulse Debugging: Data Audit & Debug Log Troubleshooting Guide –>
<!– Focus Keyword: TeamPulse debug log SuiteCRM –>
<!– Alt Keywords: SuiteCRM extension troubleshooting, TeamPulse data audit debug –>
<!– Slug: teampulse-debugging-data-audit-debug-log-suitecrm –>
<!– Meta Description: Diagnose TeamPulse issues in SuiteCRM using the always-on Debug Log, Data Audit tool, and HMAC-signed Secret Diagnostic URL. Resolve API failures and data sync issues. –>
<h1>TeamPulse Debugging: Data Audit & Debug Log Troubleshooting Guide for SuiteCRM</h1>
<p>The reliability of TeamPulse as a behavioral intelligence engine depends on the continuous, accurate flow of data from SuiteCRM. For sales managers and administrators, technical disruptions mean a loss of visibility into team performance and stalled coaching workflows. The Debug and Troubleshooting tools provide a transparent "under the hood" view of the system, allowing users to verify data integrity, diagnose API failures, and resolve connectivity issues before they impact sales management decisions.</p>
<h2>The Debug Tab: Component Overview</h2>
<p>The Debug tab, located within the Settings menu, is the primary diagnostic hub for the TeamPulse extension. It provides real-time insights into technical operations and the health of the underlying service layer.</p>
<h3>Debug Log</h3>
<p>The Debug Log is a live, scrollable record of all system activities. As of v0.9.7, logging is <strong>ALWAYS ON</strong> to ensure that critical events are captured without manual intervention. There is no toggle to disable logging.</p>
<ul>
<li><strong>Captured Events:</strong> The log records all API calls (e.g., <code>op=scores</code>, <code>op=ping</code>), errors, AI processing events, and scoring engine executions.</li>
<li><strong>Log Data Points:</strong> Each entry includes a timestamp, the specific operation name, the duration in milliseconds, the success/error status, and detailed error messages.</li>
<li><strong>Storage:</strong> Logs are stored in the server’s file system rather than the database, ensuring they persist even during database connectivity issues.</li>
</ul>
<p><em>[Image Placeholder: TeamPulse Debug Log panel in SuiteCRM Settings showing scrollable log entries with filter chips for ALL, ERROR, WARN, INFO, and AUDIT]</em></p>
<h3>Data Audit</h3>
<p>The Data Audit tool is an active reconciliation engine that compares TeamPulse’s internal data state against the raw SuiteCRM database. When a user clicks <strong>Run Audit</strong>, the system evaluates:</p>
<ul>
<li><strong>User Consistency:</strong> Matches the count of active users in the database against those loaded in the TeamPulse interface.</li>
<li><strong>Table Verification:</strong> Confirms the existence of all seven core TeamPulse database tables:
<ul>
<li><code>teampulse_config</code></li>
<li><code>teampulse_cache</code></li>
<li><code>teampulse_ai_queue</code></li>
<li><code>teampulse_journal</code></li>
<li><code>teampulse_actions</code></li>
<li><code>teampulse_schedules</code></li>
<li><code>teampulse_schedule_log</code></li>
</ul>
</li>
<li><strong>Service Health:</strong> Verifies the initialization status of core services, including the UserDataProvider and ScoringEngine.</li>
<li><strong>Environment Check:</strong> Reports the active PHP version and SuiteCRM version (specifically identifying the 7.x/8.x version rather than the SugarCRM CE base).</li>
</ul>
<h3>Secret Diagnostic URL</h3>
<p>This feature allows administrators to share system health data with external support teams securely. Access is restricted to Admin-level users only.</p>
<ul>
<li><strong>HMAC-Signed Security:</strong> The system generates a unique, signed URL that grants read-only access to the diagnostic endpoint (<code>op=diag</code>).</li>
<li><strong>No CRM Login Required:</strong> Support engineers can view the diagnostic JSON report covering table status and service health without requiring administrative credentials for the CRM. The HMAC signature ensures the URL is tamper-proof and grants read-only access only.</li>
</ul>
<h3>System Status (Right Panel)</h3>
<p>The contextual Right Panel provides a persistent summary of the environment:</p>
<ul>
<li><strong>Version:</strong> The current TeamPulse build (e.g., v0.9.9).</li>
<li><strong>Data Source:</strong> Indicates if the system is in Live SuiteCRM mode or Demo Mode.</li>
<li><strong>Refresh Stats:</strong> Displays the last refresh timestamp and the auto-refresh interval (defaulted to 5 minutes).</li>
</ul>
<h2>How to Use the Debug Tools</h2>
<p>Follow these steps to navigate and utilize the troubleshooting interface:</p>
<ol>
<li><strong>Access the Interface:</strong> Navigate to <strong>Settings</strong> in the left sidebar and select the <strong>Debug</strong> tab.</li>
<li><strong>Filter the Log:</strong> Use the filter chips (ALL, ERROR, WARN, INFO, AUDIT) to narrow down entries. The AUDIT filter is specifically designed to isolate license-related and data-reconciliation events.</li>
<li><strong>Manage Log Data:</strong>
<ul>
<li><strong>Refresh:</strong> Reload the log to see the most recent API activity.</li>
<li><strong>Copy/Download:</strong> Copy the log text to your clipboard or download it as a file for attachment to support tickets.</li>
<li><strong>Clear Log:</strong> Permanently delete current log entries to start a fresh diagnostic session.</li>
</ul>
</li>
<li><strong>Execute a Data Audit:</strong> Click the <strong>Run Audit</strong> button. Review the resulting PASS or WARN verdict. If a warning appears, review the specific list of discrepancies (e.g., table missing or user count mismatch).</li>
<li><strong>Generate Diagnostic Access:</strong> Click <strong>Reveal URL</strong> under the Secret Diagnostic URL section to generate a link for support staff. This option is available to Admin users only.</li>
</ol>
<h2>Next Steps: Administrative Actions Based on Findings</h2>
<table>
<thead>
<tr><th>Finding</th><th>Recommended Decision</th></tr>
</thead>
<tbody>
<tr><td>Audit Verdict: WARN</td><td>Check for missing tables. If counts don’t match, verify that all users are assigned to the correct Teams in SuiteCRM.</td></tr>
<tr><td>API Status: Unreachable</td><td>Perform a Quick Repair and Rebuild (QRR) in the SuiteCRM Admin panel. This often resolves entry point and navigation registration issues.</td></tr>
<tr><td>Log Error: "Unlicensed"</td><td>Navigate to the License tab. Ensure the plan ZIP matches the license key (e.g., Monthly keys require the Monthly ZIP).</td></tr>
<tr><td>Log Error: "API key not configured"</td><td>Direct the manager to the AI & Data tab to verify the BYOK settings and provider credentials.</td></tr>
</tbody>
</table>
<h2>Troubleshooting & FAQ</h2>
<p><strong>Why does the Audit show SuiteCRM version 6.5.25 when I am on SuiteCRM 7.14?</strong><br>
This occurs when the system reads the underlying SugarCRM CE base constant (SUGAR_VERSION). TeamPulse uses a corrected <code>crmVersion()</code> check that prioritizes <code>$sugar_config[’sugar_version’]</code>; the SUGAR_VERSION constant (6.5.25) is used only as a last resort. If you see the older version string, run a Quick Repair and Rebuild to update the service layer so the correct version is resolved.</p>
<p><strong>The API Log is empty despite the system being active. What is wrong?</strong><br>
Logging is stored in the <code>cache/teampulse_debug.log</code> file. Ensure that the SuiteCRM directory has the correct write permissions. If the file cannot be written to, the log area will remain blank.</p>
<p><strong>All reps show a score of 0. Is the scoring engine broken?</strong><br>
Run a Data Audit. This usually indicates that the UserDataProvider cannot read the users. Verify that the users are active and that the <code>is_admin</code> flag is correctly set (TeamPulse excludes admins from behavioral scoring by default).</p>