An Admin’s Methodology to Debugging Declarative Issues in Salesforce

As an admin, you’re responsible for the integrity of your Salesforce org. This means consistently chipping away at technical debt, fielding questions from users, and managing bugs and change requests. Debugging (or troubleshooting) declarative issues in Salesforce forms an important aspect of any Admin’s job, and depending on your ability to communicate and deliver resolutions to user issues, can either build or erode trust with your Salesforce users. 

In this article, we’ll unpack a six-part troubleshooting methodology to help you capture and resolve issues with declarative features. To access practical tools to help you analyze metadata, data, and platform issues, please check out the article on An Admin’s Toolkit for Debugging Declarative Issues in Salesforceging Declarative Issues in Salesforce. After reading this article, you should be equipped to implement a reliable and predictable bug resolution process at your organization! 

Troubleshooting Methodology 

Implementing a transparent issue management protocol that is socialized across your team is an important step in building trust with your Salesforce users. We’ll unpack a six-part methodology to reliably and predictably capture and resolve bug tickets:

1. Defining the Issue

High-quality bug tickets make triaging and issue resolution much more efficient by reducing confusion about the issue (spending time trying to solve the wrong problem) and reducing time spent clarifying the issue with users. Let’s look at the anatomy of a comprehensive bug ticket: 

Best practices for defining issues include:

• Setting a specific location (i.e. Jira board, Trello board, Salesforce Cases, etc.) where users can report issues.
• Using issue templates and required fields to ensure users are reporting issues consistently and comprehensively.
• Facilitating internal training to educate users on how to log tickets.
• Getting on a screen share meeting to see the issue before resolving it, if anything is unclear.

Developing bug ticket templates is a great way to ensure that you are collecting the relevant information from users. Supplying users with a template “soft pass” bug ticket can help to:

• Reduce the back and forth between reporters and resolvers.
• Keep an accurate record of technical issues and resolution steps.
• Improve overall issue resolution velocity.

If your team doesn’t yet have a bug ticket template or a central location that allows users to report bugs, this is a great first step to improve your issue resolution mechanism. 

2. Triaging the Issue

Once you start receiving bug tickets, you’ll need to organize and prioritize them according to their degree of criticality – this is what we call triaging. You can triage against the level of criticality of the issue, as it compares to other issues in your org, and set clear expectations for solution delivery that are realistic for your team against these levels:

Let’s take a look at how we might define these levels of criticality and set an anticipated solution delivery timeline against them:

The exact mechanism by which your team prioritizes and triages issues may change. This is okay, as long as your triaging process and solution delivery estimates are transparent for users. It’s important to note that creating transparency surrounding triaging can help build trust. You can consider:

• Determining an issue “Owner” on the team who is responsible for triaging and assigning issues.
• Developing a predictable protocol against which you triage issues.
• Setting clear expectations surrounding solution delivery according to criticality.
• Acknowledging issues promptly after they are logged, even if they are low(er) criticality and won’t be resolved immediately. 

When developing your team’s triaging protocol, ask questions like:

• Is this bug preventing the user from completing their task(s), or is there a viable workaround?
• Is this bug preventing other users or whole teams from completing their task(s)?
• Is this bug preventing whole business processes/functions (i.e. sales, financial reporting, service provision, etc.) from being completed or being completed accurately?
• Does this bug present a security risk or expose sensitive data to users who shouldn’t have access?
• Does this bug degrade data quality in my org?
• Will this bug produce more complex issues if we wait to resolve it?

3. Replicating the Issue

Once a triaged bug is ready to be resolved, the first step in fixing it is to replicate the issue in a safe environment. Bug resolution should always happen in a sandbox environment – this is to ensure any metadata or data changes you make in the resolution process won’t disrupt Production. 

Note: Consider keeping a partial copy sandbox (or a developer copy sandbox seeded with Production-like data) that is an exact metadata match with Production to use for debugging purposes. This ensures that you have a debug sandbox that is always in sync with Prod is part of a broader DevOps management process, and falls under the purview of your senior-level system architects and administrators, or DevOps managers. 

Replicating the issue is an important step in ensuring you understand the exact conditions under which the error is triggered. It can also help to determine if the bug is a result of user error or a system configuration issue that requires technical resolution.  

To replicate an issue, you should:

• Log in as the reporting user to ensure you are testing with the same system permissions and record access.
• Follow the directions in the bug ticket to recreate the issue; you should be aiming to identify the exact conditions that trigger the error to narrow the scope of testing and possible solutions If you can’t replicate the issue, you may need to:
  • Ask the user to demonstrate the issue.
  • Consider if there are metadata differences between your test sandbox and the reported environment.
  • Consider the possibility of user error.
• If you can replicate the issue, you can move on to diagnosing the cause of the issue and brainstorming possible resolutions.  

Remember to update the bug ticket to reflect any changes/additions to the issue context based on your findings from replicating the issue. 

4. Diagnosing the Issue

Once you’ve eliminated the possibility of user error and replicated the issue, you can move on to diagnosing the cause of the bug. To diagnose the cause of a bug, you can consider analyzing:

• Metadata dependencies and causes (including automation issues)
• Data changes and discrepancies
• Platform service disruptions

Analyzing across these three dimensions provides a comprehensive scaffolding to diagnose a variety of issues. Metadata issues could relate to incorrect configurations (i.e. a Validation Rule is configured incorrectly and triggers when it shouldn’t, according to the business process) or unanticipated interactions between metadata components. 

Data issues could relate to incorrect reference data, or data being (or not being) updated unexpectedly by automation (i.e., due to metadata misconfiguration or order of operations). Sometimes, Salesforce and AppExchange products experience bugs or service disruptions, which could also be explored in the case that no metadata or data issues are identifiable. 

Check out the Debugging Toolkit section of this article for more information on features and resources to help you analyse metadata, data, and platform service issues. 

5. Determining the Best Solution

Once you’ve correctly pinpointed the exact conditions under which an error occurs and its cause, it’s time to brainstorm solutions. Develop a set of solution hypotheses and test them in a sandbox. Once you’ve confirmed the best solution (which may require consultations with other team members), you can document your solution in your bug ticket and relate/attach any relevant artefacts. 

Thoroughly documenting your solution on the bug ticket is an absolutely critical part of the bug resolution process. If the bug resurfaces, or emerges in a different environment, having a well-documented solution can save precious time and energy in (re)solving the bug later on, or may add important, time-saving context should a similar bug arise in the future. 

If you are struggling to resolve an issue (or to diagnose it in the first place), you may need to escalate it to a more senior or more technical team member. Just like you needed comprehensive, clear issue documentation from users, anyone you escalate an issue to will need the same from you. This means clearly documenting your:

• Diagnosis of the issue, or possible diagnoses that you are considering (and why you are considering them).
• Testing steps, test data, and test environment.
• Attempted solutions and their results.
• Supporting functional and technical artefacts that add context to the issue.

Facilitating this kind of “soft pass” to your team members is an important step in the troubleshooting process. Remember that when you escalate an issue as an admin, it is still your responsibility to take ownership of the communication of the status of that issue and the delivery of the solution. 

Knowing when to escalate issues can be tricky. Consider the criticality of the issue (how important it is to solve quickly) and how much time it may take you to learn how to resolve it, against how easily a more senior team member might be able to fix it. It’s important to have a repeatable, transparent, and predictable escalation process for your team. 

6. Delivering the Solution 

Shipping the solution to Production needs to happen with care. Any alteration to system metadata needs to be slotted into the existing DevOps process to ensure it is appropriately tested against any other metadata changes that are concurrently in development. 

Remember that communication is key, and often communicating clearly and realistically surrounding solution delivery timelines is more important to users than delivering a solution quickly. 

Final Thoughts

Consistency is key when it comes to issue management. When thinking about building an ongoing relationship of trust with your users, it’s critical to follow a process that your team can rely on. 

Ensuring that you are capturing high-quality bug tickets, triaging with transparency, thoroughly replicating and diagnosing issues, and determining the best solutions in a safe environment before delivery helps to ensure that you resolve bugs to a high degree of quality, in a manner that your users can grow to trust.