An Admin’s Toolkit for Debugging Declarative Issues in Salesforce

Troubleshooting issues in Salesforce isn’t easy. With a constellation of metadata components, complex data, and increasingly sprawling platform functionality, analyzing systems during the debugging process is a tricky business. Admins combine platform fluency with deep org intel to troubleshoot effectively. Whether you are a seasoned admin or someone just starting your career, having a reliable process for debugging and a toolkit to help you cover your bases during troubleshooting can help ensure you resolve issues for your users efficiently and effectively. 

In this article, we’ll unpack a set of practical tools and resources to help you debug declarative issues in Salesforce. After reading this article, you should be equipped to tackle metadata, data, and platform service issues in your org!  

Keen to learn more about debugging? Check out An Admin’s Methodology to Debugging Declarative Issues in Salesforce for a six-part troubleshooting methodology. 

The Admin’s Debugging Toolkit

Troubleshooting issues in Salesforce is complex, particularly in mature orgs where they contain a degree of technical debt or may have been designed when best practices weren’t what they are today. Analyzing issues is a critical step in the debugging process and helps to diagnose the root cause of a bug so that a solution can be designed and delivered. 

There are a number of tools and resources that can be leveraged to help admins comprehensively diagnose bugs by analyzing metadata configuration and dependencies, analyzing data integrity, and identifying platform service disruptions.  

Analyze Metadata Issues

The majority of bugs in your system will likely be caused by metadata issues. Metadata components being misconfigured (i.e. a validation rule wasn’t correctly configured and allows a data change to pass when it shouldn’t, according to the business process), or dependencies between metadata components causing unforeseen issues (i.e. a Flow updates a field, but the field update is incorrectly blocked by a Validation Rule, causing the Flow to error). 

Metadata issues can be complex to debug. Luckily, Salesforce has several tools that admins can use to support the debugging process:

1. Setup Audit Trail

When we work in larger teams, it can be tricky to keep track of who’s done what. Setup Audit Trail acts as a log of all metadata changes to your org. This simple feature is priceless when examining recent metadata changes during the debugging process. 

It tells you what was changed, when it was changed, and who changed it. Identifying this critical information can help steer you to the correct person to discuss changes with, particularly in multi-admin teams. Setup Audit Trail is accessed via Setup > View Setup Audit Trail:

2. Event Monitoring

Similar to Setup Audit Trail, event monitoring allows admins to view actions and changes in an org. Events refer to various actions taken on the platform and can be particularly useful in troubleshooting security issues in Salesforce. 

Event monitoring increases your team’s capacity to uphold security, ensure compliance, improve operational efficiency, and preserve system integrity.  It  provides tracking for many types of events, including:

• Logins
• Logouts
• URI (web clicks in Salesforce Classic)
• Lightning (web clicks, performance, and errors in Lightning Experience and the Salesforce mobile app)
• Visualforce page loads
• Application programming interface (API) calls
• Apex executions
• Report exports

Event monitoring is accessible via Setup > Event Monitoring (please note that Event Monitoring may need to be enabled in your environment; always consult an Architect before enabling settings in live orgs).

Please note that the event types you can access and how long the files remain available depend on your Salesforce edition:

• Developer Edition organizations have free access to all log types with one-day data retention.
• Enterprise, Unlimited, and Performance Edition organizations have free access to the insecure external assets, login, logout, and total API usage event log files with 1-day data retention. For an extra cost, you can access all log file types with up to 1 year of data retention.

3. “Where is This Used?” Button

The “Where is this used?” button is a nifty feature sourced by the IdeaExchange and released by Salesforce in Winter ‘20. This button, locatable on a field page within the Object Manager, displays a list of references to that field within the system.

In large, complex orgs, the ‘Where is this used?’ button can be extremely useful in identifying references to fields in:

• Formula fields
• Validation Rules
• Approval Processes
• Flow automation
• Apex classes, etc. 

Understanding the linkages between metadata in your org can support the debugging process by helping you to establish the ways in which data, contained within fields, is being manipulated and changed.

4. Data Dictionary

Data dictionaries (perhaps more aptly referred to as metadata dictionaries) serve as a guide to your field-level metadata. Data dictionaries track key information relating to fields to help admins understand the purpose of each field in the context of the system, helping to answer key questions like:

• What type of field is this?
• Where is this field used (i.e. page layouts, and reports)?
• Who manages and accesses this field? Who doesn’t?
• Is this field referenced in any automation? 
• Is this field dependent on any other fields, automations, or integrations? 

A typical data dictionary may include:

• Field label
• API name
• Field type
• Description
• Help text
• Created and last updated dates
• Available in the UI? (Y/N)
• Where used 
• Dependencies and automation references 
• Who owns/manages
• How is this field updated (i.e. user vs system)

While certain tools/platforms like Elements.cloud can help to facilitate smart, in-system data dictionaries that are related to metadata components and business requirements, old-school data dictionaries that exist as off-system documentation artefacts will also suffice if they are kept up to date with every new release of functionality.

5. Setting Trace Flags and the Debug Log 

Trace flags are a developer tool that allow admins to trace various events (i.e. execution of Apex methods, SOQL queries, and DML operations) executed by a specific user, to a defined level of granularity. Once the trace flag concludes, the results of all actions executed during the trace window are written to a log file, which can be reviewed from the debug log. 

Trace flags can be set via Setup > Debug Logs, then creating a new Trace Flag. Once the trace flag has concluded, the results will be written to a log file under ‘Debug Logs’ where it can be reviewed for debugging purposes:

6. Salesforce Order of Execution

Understanding the order of execution in Salesforce is crucial to debugging data issues and conceptualizing how your metadata stitches together to enable functionality. Order of execution refers to the order in which the Salesforce platform processes various operations within a save transaction. 

Refer to the infographic below to see all the things that Salesforce is evaluating every time you save a record:

Investigating the order of execution can sometimes help to uncover the cause of tricky bugs. 

Analyzing Data Issues

In addition to looking under the hood of your metadata, analysing your actual data is an important step in the debugging process. Analyzing data and data changes can help to pinpoint when issues are happening (i.e. if intended data changes are disrupted due to an issue in the order of execution) and if data integrity may be compromised (i.e. reference data is corrupted). 

1. SOQL

Salesforce Object Query Language (SOQL) is Salesforce’s version of SQL, and allows admins to query data quickly and efficiently using the Developer Console, or other Developer tools. Some use cases for SOQL debugging include:

• Querying data when certain fields are not accessible via the UI.
• Querying data when you need to understand data changes that live across multiple different but related objects.
• Querying data changes that may be impacted by the Salesforce order of execution.

Check out the Admin’s Guide to SOQL for more use cases and examples of how to use SOQL to enhance your debugging efforts. 

2. Reports

If you need to analyze data changes in your org but don’t have the Developer skills to execute SOQL queries, don’t fret. You can always query data in your org using Salesforce reports. Reports offer a simple, declarative way to visualize record data from your org. If you need help learning how to create reports in Salesforce, check out the How to Create a Report in Salesforce resource. 

Analyze Platform Service Disruptions

In the rare event that Salesforce experiences a platform service issue, there are resources you can consult to understand the scope and resolution timeline for the issue. 

3. Salesforce Trust

The Trust website is the primary resource for all platform service-related intel. By inputting your org’s instance Id into the Trust site, you can search for service disruptions that may be impacting your org. 

You can also search for service disruptions across Salesforce’s portfolio of products on the Trust website:

4. Known Issues

Salesforce’s Known Issues is a repository of platform bugs/issues that Salesforce is aware of and working to resolve. Issues are searchable by category, status, release, and keyword. 

Consulting Known Issues for status updates on platform bugs can help you communicate resolution ETAs to your impacted users. 

Additional resources

In addition to the above tools, admins can always consult a variety of validated online Salesforce resources that are available to all Trailblazers:

1. Salesforce Help for trusted resources, knowledge articles, and best practices. 
2. Ask Agentforce for AI-supported access to troubleshooting advice and links to resources. 
3. Trailblazer Community Groups to ask questions to other Salesforce users and professionals; Trailblazers are active in the community and always keen to help other admins solve problems. 
4. Admin Site for admin-specific tools, tips, and resources.
5. Developer Site for Developer-specific tools, tips, and resources. 
6. Architect Site for Architect-specific tools, tips, and resources. 

Of course, there are also many non-Salesforce-owned online resources, like Salesforce Ben, that provide high-quality Salesforce content that can support your overarching command of the Salesforce platform. 

Troubleshooting Checklist

Now that you’re equipped with a Swiss Army knife of admin tools and resources to support troubleshooting, let’s cover a few common issues that you can keep top of mind to expedite bug diagnosis and resolution. 

You can think of the checklist below as a quick and easy way to identify common bugs by asking a few simple questions for each common type of issue:

Object Permissions and Record Access Issues

• Is the user assigned the correct profile and permissions?
• Is the user assigned to the appropriate role and/or public groups?
• Is data visibility being altered by conditional visibility components in the UI?
• Is data access in lookup fields being altered by Lookup Filters?
• Does the user have the appropriate field access (FLS) to see data in lookup fields, reports, and dashboards?

Reports and Dashboards 

• Do Report Types contain the fields that users are trying to reference in reports?
• Are reports and dashboards being stored in shared folders?

Automation

• Is the automation activated to its most recent version in the environment?
• Is the automation configured to trigger correctly?
• Has the Salesforce Order of Execution been properly accounted for in the design?
• Is the automation taking all business scenarios into account, or is it allowing unwanted scenarios to pass? 

Final Thoughts

Debugging is a science! As an admin, having a reliable methodology to support troubleshooting and debugging toolkits can dramatically help reduce the time and frustration associated with bug resolution. Happy debugging!