Debugging Timeline Items

The Timeline app provides a powerful debug tool that helps administrators and developers troubleshoot timeline configuration issues, test queries, and identify field permission problems. This tool is accessible through the Timeline Setup page and provides detailed insights into how timeline items are retrieved and displayed.

Accessing the Debug Tool

1. Navigate to the Timeline Setup page (available in the App Launcher under "Timeline Setup")
2. Find the timeline configuration you want to debug in the list
3. Click the Actions menu (dropdown button) to the right of the configuration
4. Select Debug from the dropdown menu

This will open the debug interface in a new mode within the Timeline Setup page.

Debug Tool Interface

The debug tool interface is split into two main sections:

Left Panel - Live Timeline Preview

• Parent Record Id Input: Enter the ID of a specific record to test the timeline against
• Timeline Preview: Shows a live preview of the timeline component in debug mode, displaying any warning messages for missing field permissions or other issues

Right Panel - Query Analysis

• Query Breakdown: Shows individual queries for each timeline setup item, organized in expandable sections
• Query Execution: Execute the chosen query and display the results as JSON.

Understanding Query Sections

Each timeline setup item gets its own expandable section in the right panel:

Query Display

• Raw Query: Shows the exact SOQL query that will be executed for this timeline item
• Parameter Substitution: When you enter a Parent Record Id, the query shows with actual values substituted for parameters like :recordId, :ownerId, etc.
• Copy to Clipboard: Use the copy icon to copy the query and test it directly in the Developer Console or other SOQL tools

Query Execution

• Run Query Button: Execute the query with the current parameters and filters
• Results Display: Shows the raw JSON results returned by the query
• Debug Messages: Displays any field permission warnings or other debugging information

Common Debug Scenarios

1. No Timeline Items Appearing

Symptoms: Timeline is empty or missing expected items

Debug Steps:

1. Enter a valid Parent Record Id in the debug tool
2. Check each query section to see if queries are returning results
3. Look for error messages in the query results
4. Verify the parent lookup field is correctly configured
5. Check if WHERE conditions are too restrictive

2. Field Permission Issues

Symptoms: Timeline items appear but some information is missing

Debug Information:

• Debug messages will show Field '[FieldName]' is not accessible on '[ObjectName]'
• These messages appear both in the live timeline preview and in the query results
• Fields without read permissions are automatically filtered out by Salesforce security

Resolution:

• Grant the user appropriate field-level permissions
• Or remove the inaccessible fields from the timeline setup configuration

3. Query Performance Issues

Symptoms: Timeline loads slowly or times out

Debug Steps:

1. Copy queries from the debug tool
2. Run them in the Developer Console Query Editor
3. Check query execution time and row counts
4. Look for missing indexes or inefficient WHERE conditions
5. Consider adding more restrictive filters to limit result sets

4. Date Filtering Problems

Symptoms: Timeline shows incorrect items for selected date ranges

Debug Steps:

1. Use different date filter options in the debug tool (All Time, Last 7 Days, Last 30 Days, etc.)
2. Examine how date parameters are substituted in the queries
3. Verify the time field configuration is correct
4. Check if the time field is a Date or DateTime type and ensure proper filtering

Debug Mode in Production

The Timeline component itself also supports debug mode for end users:

Lightning Record Pages

When configuring the Timeline component on a Lightning record page:

1. Edit the page in Lightning App Builder
2. Select the Timeline component
3. Enable the Debug Mode property
4. Save and activate the page

This will show field permission warnings directly in the timeline for end users, helping them understand why certain information might be missing.

Debug Mode Features

• Shows warning messages for inaccessible fields
• Displays tooltips explaining why certain timeline items might be incomplete
• Helps users understand field-level security impacts

Best Practices for Debugging

1. Test with Different User Profiles

• Use the debug tool while logged in as users with different permission sets
• Check how field-level security affects timeline display
• Ensure timeline items appear correctly for all intended user types

2. Query Optimization

• Monitor query row counts in debug results
• Keep queries under the 2000 record limit
• Use appropriate WHERE conditions to filter results
• Consider date range limitations for better performance

3. Regular Maintenance

• Periodically check debug messages for new field permission issues
• Test timeline configurations after permission set changes
• Verify queries still work after Salesforce releases or customizations

4. Documentation

• Document any custom configurations or workarounds discovered during debugging
• Keep notes about field permission requirements for each timeline setup
• Share debugging insights with other administrators

Troubleshooting Common Error Messages