More Ways to Troubleshoot Your SCA Site

When working on your SCA modules, it's possible your code to fail first time. Knowing what to do — and what to check for — can be difficult.

I've written previously about things you can do in the browser to troubleshoot your site. This article will give you ideas about what to troubleshoot your site and debug your code fails when it fails, ranging from basic JavaScript checks to NetSuite-specific stuff.

Check Code Quality

As a lot of SCA code is written in JavaScript, and with it being a particularly unforgiving language, you should first turn your attention to the syntax of your JavaScript. If, for example, your browser console has returned a JavaScript error then you should be able to identify the file name and line number of where the error appears. Using that information, examine that and the preceeding lines for incorrect synatax such as:

  • Missing commas, semicolons, brackets, square brackets, curly brackets, etc.
  • Capitalization and camel case. Remember, methods, helpers, variables, etc., are all case-sensitive. It's not uncommon to get a fooBar is undefined error because you accidentally called your variable foobar.
  • Correct spelling. For example, in our tutorial module we frequently reference 'artist' and 'artists' — make sure you're using the right one. Also note that API methods can also have quite long names, which are case-sensitive too, so spelling them correctly is important.

Use JSHint

JSHint is built into the SCA Gulp distribution as a task. JSHint is a task that helps detect errors and potential problems in JavaScript. You can run JSHint to run on all code in the SCA distribution but this is cumbersome, instead it is best to run it simply on the module that you are having problems with. For example, if I want to run it on a module called Artist then I can type the following command when in my distribution directory:

gulp jshint --modules=Artist

You can chain additional modules to the end using commas.

For more information, see their website.

Use console.log();

If your JS isn't behaving as expected, or there seems to be incorrect values, objects or parameters being sent to functions, put some console.log() commands into your JS and see what's returned in the developer console. There have been a few times, for example, that putting console.log(this) and console.log(myVariable) has helped me find out what is going on.

SCA and Backbone-Specific Checks

If you're new to SCA (or the libraries that SCA uses, such as Backbone) you may be unfamiliar with things such as the application's structure or coding conventions.

Issues with Incorrect define Statements (RequireJS)

When you use define at the start of a JavaScript file (such as you would for models, views and collections) you are defining the requirements for that file. However, basic mistakes in this statement can have repurcussions where your code relies on another file but you haven't required it properly. Below is an example of a properly coded define statement:

define('Artist.List.View'
, [ 'Backbone'
  , 'Backbone.CollectionView'
  , 'Backbone.CompositeView'
  , 'Artist.Details.View'
  , 'artist_list.tpl'
  , 'GlobalViews.Confirmation.View'
  , 'jQuery'
  ]
, function (
    Backbone
  , CollectionView
  , CompositeView
  , ArtistDetailsView
  , artist_list_tpl
  , ConfirmationView
  , jQuery
  )
{
  'use strict'
  ...
});

With that example, note the following:

  • The string at the start of the statement (Artist.List.View) must match the title of the file; if this incorrect and another file tries to call it then you'll get an error like Uncaught TypeError: ListView is not a function.
  • Next is the list of files that this file depends on. Note that in the cases of JavaScript files, we are using the name that we use as the strings in the define statements; an incorrectly typed name (or non-existent module) will return something like: Uncaught Error: Script error for: Artist.Details.Viwe.
  • In the function we pass as parameters the names we want to use when we refer to the dependencies in the module file. Theoretically you can call them whatever you like as long as:
    1. The name is used consistently throughout the file.
    2. The order that you name them matches the order that you name them.
  • Note, therefore, our naming conventions are strictly guidelines and not requirements but we strongly recommend that you adopt the same conventions to help ensure consistency. A typo or incorrect naming will likely return an error such as: Uncaught ReferenceError: CollectionView is not defined.
  • Finally, 'use strict' is recommended. Although unlikely, using strict mode may return some errors that otherwise wouldn't have been returned. In other words, your JavaScript may be failing silently but strict mode will give them a voice.

Error Screen Starting with [object Object]

This is caused by trying to use a module where the service does not have the name value set in the backend model. For example, my Artist module uses the following pattern of:

define('Artist.Model'
, [ 'SC.Model'
  , 'underscore'
  ]
, function (
    SCModel
  )
{
  'use strict'

  return SCModel.extend({

    name: 'Artist'

  , get: function(id)
    {
      ...
    }

  , list: function()
    {
      ...
    }

  , create: function(data)
    {
      ...
    }

  , update: function(id, data)
    {
      ...
    }

  , remove: function(id)
    {
      ...
    }

  , validation:
    {
      ...
    }
  });
});

Declaring a value for name is perhaps something you might forget to write as the others (such as get and remove are functions used by the service file (and things like validation and list being specific to the module).

Gulp, Node and Deployment Problems

Gulp is a powerful tool in SCA development: importantly, it compiles and deploys code to the NetSuite and local servers. You can read online about general things to troubleshoot Gulp, but here are some SCA-specific ones you might encounter.

Changes Not Reflected on Local Server

If you've saved your changes and you've refreshed your local site and not seen the changes appear, the first thing you should check is that the local version of Gulp is running. Remember, you can start this by going to the parent directory of your SCA code and running gulp local.

If it is running, check the URL of the page you're viewing and see if you're actually using the local .ssp file. If your session has expired and you need to log in again, it'll redirect you to the hosted version of the SSP, rather than the local one. All you need to do is change the URL, from, say, my_account.ssp to my_account-local.ssp.

gulp local works by 'watching' for changes to files. It's entirely possible for this process to fail if it's already running; thus, you can try stopping and restarting the service if you think it's not watching. This is necessary, in fact, if you've just added new files or directories as Gulp does not watch for new files — it only watches files that already exist.

Remember, as well, that there are a number of configuration files that are required to ensure Gulp compiles correctly:

  • ns.package.json — located in the top level of every module folder. It acts as a catalog for your resources, telling Gulp which directories and files within the folder are the module's JavaScript, services, Sass, etc. If you run Gulp without this file then you'll like get an error that says someting like: Error: Module not found: Artist.
  • distro.json — this is in the top level of your SCA folder and comes with the distribution. It informs Gulp, among other things, of all the modules to be included in the distribution before it is deployed. When adding a new module you must check that it is included in the relevant places, such as the following:
    • modules — effectively the module folder location.
    • tasksConfig > javascript > dependencies — the name of the module file.
    • tasksConfig > ssp-libraries > dependencies — the backend model you're going to be using.
    • sass > applications > [name of application] > dependencies — if you're including Sass then you'll need to specify the name of the module under the application the module is being used in.
  • More complex modules will also need to be included in distro.json in other places. Remember, keep standard JavaScript checks in mind: casing, spelling and syntax; numerous issues can be resolved by ensuring that minor errors are resolved.

Cannot Find Service on Local Server

If you've just added a service, remember that you will need to deploy it to your hosted server as it cannot be accessed locally. If you just want to deploy your services (and not run through the full deploy sequence) you can run the following command:

gulp deploy --dev

Essentially, the --dev flag tells the deploy script to only upload backend code.

Old Versions of Module / Global Images are Shown

There are two things that cause this problem.

Firstly, it's possible that the image is cached in browser. Some browsers, such as Chrome, allow you to do a hard reload and cache clear on refresh (note that this is different to the 'hard reload' option. In Chrome, you need to open the developer tools open and then click and hold on the refresh icon. The "empty cache and hard reload" option will be available. You can also simulate this by simply using a private/incognito browsing session.

Secondly, you may not realise but these images are not served locally. If you've changed an image locally as part of your customization, you need to upload it to your site first. If you're unwilling to do a full deploy of your code, you can upload the changes to your site via the File Cabinet. If you don't want to overwrite the images then you could name your new images something different.

Check the Docs

As the product matures and take-up improves, we're getting more feedback from developers about the problems they encounter. As we do, we'll update the documentation around troubleshooting to help alleviate any problems you may face. Do a search for 'troubleshoot' on Developers.SuiteCommerce to find them.

Further Reading