General Troubleshooting Process and Checklist

Discussion Knowledge Base
1

Here are some basic steps you can take when confronted with issues in Skuid. Sometimes troubleshooting can be relatively straightforward. The more complex the scenario, the more it pays to work carefully through each of these steps.

#0: Design before you build (and along the way)

Skuid is a tool for building tools. Sometimes the tools you’re building are themselves fairly complex. As you build and troubleshoot, take time to reflect on the design and intention behind your project.

Ask yourself:

What will the thing I’m building enable users to do, and why?

#1: Get insight into the issue

Most Skuid issues can be framed as responses to these two questions:

  1. What does the user expect to happen in this scenario?

  2. What’s actually happening?

Also observe:

Where the issue is occurring (e.g. runtime, the App Composer, the Lightning Experience, Visualforce, which page(s), which version of Skuid…)

Are there any errors in the browser console? If there are errors, try searching this community for the text of the error message to see how other users have resolved it.

Use the Skuid debug API in the browser console at runtime to dig into pages, models, components, and action sequences.

#2: Reproduce the issue

Ask yourself:

  • Can I make this issue happen again? Is a certain scenario or combination of settings known to cause the issue?

  • What was the affected user doing just before the issue occurred? Before that?

  • Does the problem only occur on this page?

  • Does it only occur for a specific user or a group of users?

  • Does it only occur in this environment? (e.g. Salesforce org, Skuid site, Visualforce, Lighting, Salesforce Community…)

The answers to the questions above will help guide the rest of your investigation (see steps #3-5 below). Once you have gathered enough information about the issue to be able to reproduce it consistently, you can troubleshoot smarter.

#3 Isolate the issue

Here are 3 methods that we use as Skuid Technical Support Engineers to narrow down the source of a problem:

A . “Map” the page at runtime to the page in the composer

If you haven’t already, it’s time to open the App Composer. Figure out which models, components, and logic contribute to the behavior. This becomes increasingly complex based on the complexity of the page. Fortunately Skuid’s new Page Index feature helps you navigate complex pages with ease.

When looking at a page in the Composer and trying to figure out how it works, it’s helpful to ask yourself:

B. Simplify

The more complex the scenario, the more it helps to rule out page elements that are NOT involved in the error. Finding the simplest way to reproduce the error can help identify possible solutions.

  • Remove all unnecessary page elements including inline Javascript and CSS, models, components, action sequences, display logic and custom Design Systems or Themes.

  • Use the XML view and comment out sections of the code (e.g. all custom code, specific action sequences, models, and components). Use to close the comment. Make sure the XML maintains its integrity (Skuid will warn you if it’s not correct). The advantage of this method is that restoring the page to its original state is as easy as removing the comments.

  • Clone the page and gradually strip it down until you stop experiencing the issue.

  • Create a brand new page and try to recreate the issue as simply as possibly from 0.

C. Have the page talk to you

  • Add a simple component, like the Text component, and bring your problem field into it. This is useful, for example, when you’d like to check if a field is displaying correctly for a certain user or group. You can also use this method to assess if Ui-Only fields have been correctly populated and/or updated.

  • When debugging actions sequences, you can use the Show Message action to alert yourself to when certain behavior is or should be occurring. Similarly, you can use console.log(); to show messages at strategic moments in a custom JavaScript snippet.

  • Use named page revisions to keep track of changes you’ve made to the page and which versions show the issue, e.g. “Removed Snippets - Error Persists”

#4 Identify the root cause

Once you’ve broken the issue down to its most basic state, you can start to gather more information about what the user expects to happen versus what Skuid expects to happen and what is the root cause of the issue. These causes tended to fall into 3 buckets:

1. Configuration issue:

This occurs when the page is missing information it needs to be able to behave the way users expect. In most cases, the solution involves adjusting page elements to provide the page with the information it needs to behave as intended.

2. Product defect:

If the page has all the information it needs to behave the way the user intends and is still failing, then it may be a sign that Skuid isn’t functioning as intended. In this case, the short term solution is to find a workaround while waiting for the issue to be resolved.

3. Feature gap:

In some cases, the desired functionality needs to be built out, either at the app level or the product level:

  • Revisit the design in the context of the discovered limitations. You can often think creatively and find a way to achieve the desired functionality declaratively in Skuid using the action framework, display logic, design systems etc.

  • If a declarative solution isn’t possible, you can extend Skuid with custom JavaScript or CSS.

  • In the case of where the functionality would universally benefit Skuid users, you can request a product enhancement.

#5 Start trying things to resolve the issue

Once you’ve identified the cause of the error and simplified it as much as necessary you can start making changes in order to solve the issue or discover a workaround. (Often this happens at the same time as #3 and #4, as you start tweaking the page setup to see what might be causing the issue.)

Get help with an issue:

1 Like