5+1 Admin Tips: Troubleshooting in Salesforce - Part II

In the previous post of this series we barely got to scratch the surface to get on our road to troubleshooting. This time we’ll see how we can dig deeper to get more information that can help us diagnose the issue.

Tip 4: Seriously, I mean everything, really, E-V-E-R-Y-T-H-I-N-G

As mentioned before, even an imperceptible action could be anything from determining to finding the error cause and fix. Any simple action could inadvertently trigger a course of action that leads to it. But reproducing or getting to the error should be only 1% of the time spent in it, and the remaining 99% should be fixing it. And to quickly get to the error you need to have the steps to reproduce it. This means the user reporting the error needs to tell the support team everything they did to get to it. Consider the following when you report issues:

Nobody knows what you’re talking about

Systems constantly grow, change, have features added and removed. The same way that it is not logical to expect an end-user to be familiar with all features (likely it’s only the ones they usually need to use for their division), you can’t expect someone from the support team to be either. Questions such as:

• “Remember that flow I told you about?” → Useless to ask, which flow and when did you tell them? The support team does not have only one request, so you’re not saving any time by expecting them to remember something that happened some time ago. Even if they did remember, if they were to push the request to somebody else, they need to have the specification of the request in writing, as opposed to telling one another what they may or may not remember.
• “Has anyone seen this error?” → Errors can have many possible origins and whether the error is too generic or too specific, if an error is not clear to an end user, then it is rarely something anyone else may know the answer to just by reading it.

Anything you mention needs to be defined so that anyone reading it knows what you’re talking about. For example: “I got an error with a transaction”. Nobody is going to reply “Oh, of course, that one and only error that ever happened with a transaction, lemme fix it for ya”. The sarcasm level would be off the charts. There’s a lot of information that needs to be provided in order for that to start becoming a question, such as: What is a “transaction”?

This should be the first question that should be answered, but that should not even need to be asked since you should define what you did from the start. You might be very familiar with that feature but somebody else may not, so you will not be saving any time by using shorthand, nicknames or acronyms. You cannot expect somebody to give you options of every possible answer:

• Is it the Opportunity standard object that was renamed “Transaction”?
• Is there a custom object called “Transaction”?
• Is it an Opportunity of record type “Transaction”?
• Is it even called “Transaction”? What if there’s several objects in the org with the word Transaction: “Account Transaction”, “Fund Transaction”, not one called only “Transaction”, which one is the “Transaction” you’re talking about?

It’s another instance of “Bob”: is it “Bob Smith”? “Bob Johnson”? “Robert A Smith”? “Roberto Jackson”? If for every bit of information the support team will need to provide the billions of options that there could be, then there will never be a resolution. You saw the issue, you got to it, just describe everything on how you got there. Basically, if you see an elephant, you’re not going to tell someone you saw “something with four legs” and wait for them to give you a complete list of furniture (which can also have four legs) for hours, until they give up on furniture pieces and move on to list animals, until they eventually hopefully get to “elephant” for you to say “Yes, that one”. You saw it, call it as it is unequivocally from the beginning.

What do you mean by “everything”?

Everything means anything that is related to the issue. An Administrator cannot be asking:

• Did you go to a Contact? Did you go to an Account? Did you go to X? Y? Z?
• Did you click button A? B? C?
• Did you click link T? U? V?
• Did you fill in the first field with “a”? “b”? ”c”? The second field with “d”? “e”? ”f”?

just so that the reporter can answer yes or no until confirming a yes for every step. There’s no way to put together a list of all the possibilities of what needs to be done to get to the error. This would take forever and it’s not productive at all. The reporter is the one who saw the error, they were on that screen, they should be able to identify how they got there.

Everything is also not something that is not related to the issue. For example: if you give a complete backstory of how the company was founded by two orphan brothers and all their struggles growing up, that’s not going to be related to the error to need to have that conversation. Sometimes users get caught up with unrelated details that don’t really help, don’t add information, and add confusion as to why that was brought up instead of something really important that was right in front of them.

This is the problem when reporting issues and asking users to tell us everything: everything becomes unrelated stuff and then the most important parts of the process to reproduce the error (steps that they did themselves and should be able to articulate) somehow don’t fall into that category.

What do you mean by “how you got there”?

When an Administrator asks you “how you got there” it doesn’t mean that you need to tell them what caused the error or how to fix it, it means that you need to tell them how to get to the error. This is a major issue because end users always try to “figure out” what it could be, that they are being asked to determine the cause of it, instead of just telling what they did so that the support team can actually determine how the error was caused. Take this exchange for example:

- What did you enter?

- I edited the record and then I got the error when I saved.

- ok, but what did you enter? What did you modify in the record?

- I don’t know, I just saved the record.

- Yes, I understand that you just saved the record and that before that you click the Edit button to edit it, but what did you do between the click of the Edit button and the Save button? Did you modify any data?

- Mmmm, I don’t know, I think it’s the date field that is blank.

- Did you modify the field to blank it out or was it already blank?

- No, I didn’t modify it.

- So did you change any field between the click of the Edit button and the click of the Save button? 

Basically with the last question you are back to square one. No matter how you ask or how many times, you don’t get a direct answer such as: “I clicked Edit, modified the close date to today and clicked Save.” Make sure you explain to the end user the difference of what you are asking them to do and what they think you are asking them to do. How to get to the error is just a sequence of steps they should be able to provide because they already did those steps and they are the only ones who know what they did. It has nothing to do with whether they know what caused the error or not.

Troubleshooting The Troubleshooting Process

So if you are reporting everything (as we defined it above) of an error, here’s some best practices to follow:

• Don’t provide information that is not relevant to the flow of actions that lead to the error (as mentioned in tip 2).

• Don’t provide information about your emotional journey (as mentioned in tip 2).

• Provide information about the environment where the issue was found (as mentioned in tip 3).

• Provide information about the user who ran into the issue (as mentioned in tip 3).

• Provide definition of any term used (as mentioned in tip 4 - Nobody knows what you’re talking about).

• Don’t use acronyms or terms without defining them. The reader may not be familiar with particularities of your division or that part of the system to understand what certain terms mean.

• Provide steps on how to get to each step. For example, don’t start with “edit the contact”, walk the reader through how to get there:

• Go to the Contacts tab.
• Select the Created Today view.
• Select any contact on that list.

• Click the Edit button on the contact    

• Provide details of the type of record that the error happens to. For example:

• The record must be a Contact of record type “Client”.

• The contact must have a populated Email and Phone Number.

• Provide steps of actions performed to get to the error.

• All steps should be concise and to the point.

• Don’t include steps that consist of several actions all rolled into one step. Separate them in short punctual actions.
• Include names and placing of the elements where you perform the actions. For example, If it’s a button that you click, there could be many on each layout and not all layouts may have the same buttons, so that’s why it’s important to have the steps previously defined to get to the right page as well as this one:
• Click on the “Search Programs” button at the top-right of the page layout.

• A form to search programs is displayed at the center of the screen.

• All steps should be in chronological order of execution.

• Create bullets with each step and each flow of actions or scenarios.

• The bullets can be numbered:
• 1. Go to the Contacts tab
• 2. Select the Created Today view
• 3. Select any contact on that list.
•  or you can add your own naming and numbering, for example:
• Step 1: Go to the Contacts tab
• Step 2: Select the Created Today view
• Step 3: Select any contact on that list.
• Use a bullet for each step, and sub-bullets for nested steps. For example:
• If the close date is less than a year ago:
• The amount must be greater than 10,000.
• The expected revenue must be at least 40%.
• If the close date is greater or equal than a year ago:
• The amount must be greater than 5,000.
• The expected revenue can be any value.
• Don’t do a memory dump, organize the information you provide and make it easy to read. For example:
• Memory dump:
• When a Person Account is Created or Updated and the related Contact’s Member Summary field is equal to “Non-member” and the related Contact’s Email Opt Out is False, a Campaign Member record will be created between the Contact record and Campaign for the Region.
• Organized:
• When a Person Account is Created or Updated:
• Conditions:
• Related Contact’s Member Summary field is equal to “Non-member”
• AND
• Related Contact’s Email Opt Out is False
• Expected Result:

• Campaign Member record will be created between the Contact record and Campaign for the Region.

• Provide steps of data entered including previous value and new value.

• If the close date is blank then fill it with a date at least 10 days before today.

• For the amount enter a value greater than 10,000.

• Provide links to sample records.

• Sample records are records that an Administrator is able to experiment with or take as an example of all the conditions a record must meet to reproduce the error. For example:

• I’ve been performing these steps with the following record: https://test.lightning.force.com/lightning/r/Contact/0030y000000aaalAAD/view

• Don’t provide names of records, since there can be several with same or similar names a link is more direct. Since the support team needs to get to the error and in order to get to it they need to get to the record where it happened, the fastest way is to have the link (instead of searching it by name or typing it from an image, which could lead to confusion)

• A link is not a replacement for the other types of steps described above (a link doesn’t tell you what data to enter or what to press to get to the error), it is just to facilitate sample data.

• Provide screenshots of the records or errors.

• Images help but they are complementary.

• An image is not a replacement for the other types of steps described above (an image doesn’t tell you how you got there, what data you entered or what you pressed to get to the error).

• Don’t think that a screenshot is as good as a link to the record. The support team should not have to type an Id from a blurry image to search for the record.

• Provide a video screen capture of how you navigated from the moment you log in, through all the steps until you get to the error.

• A video helps but it’s also complementary.

• A video is not a replacement for the other types of steps described above.

• Don’t think that a video is as good as a link to the record. The support team should not have to type an Id from a video to search for the record.

• Provide date and time as accurately as possible for when you started experiencing the issue.

• The date can help determine the origin of the error (the date may align with a new release date, something that became available from a critical update or some other event).

• The time can also help determine the origin of the error (the time may align with the time a certain process runs in the background, a release that was pushed at that time or some other event).

Every possible item of information is needed and has its own role in the troubleshooting process. You cannot put together a puzzle without all the pieces, and each piece has its own value.

The problem should be putting the pieces together. Then you’re part of the solution.

The problem should NOT be finding the pieces first. Otherwise you’re part of the problem.

In the next and last post of this series we’ll dive deeper into how to finally reproduce the error and troubleshoot. Stay tuned…

What do you think of the process of troubleshooting? Do you have any recommendations to get more information when users are playing difficult? Tell me all about it or suggest topics you want me to write about in the comments below, in the Salesforce Trailblazer Community, or tweet directly at me @mdigenioarkus. Subscribe to the Arkus newsletter here to get the top posts of the Arkus blog directly to your inbox.