Post Featured Image

Announcement: SuiteCommerce and SuiteCommerce Advanced 2019.2

We are pleased to announce the forthcoming release of SuiteCommerce and SuiteCommerce Advanced 2019.2, the latest update to our commerce software.

This blog post will highlight the features I think most important to commerce developers, so I strongly recommend also reading the release notes in full so that you can see everything we have included in the release.

Architectural and Developmental Changes

2019.2 ushers in significant changes to the structure of the core commerce code bundles. In short, three new technologies are being introduced:

  1. TypeScript (including ES6+ support via transpiling)
  2. SuiteScript 2.0
  3. SuiteCloud Development Framework (SDF)

As of this release, the migration to these new technologies is not yet complete but they are at a point where we consider it prudent to discuss them so that you, as developers, can prepare for (and start using) them today.

All three of these represent the culmination of a lot of work – and that work is on-going. These are serious architectural changes, and changes to the way that we expect developers to interact with our products. This is probably the biggest code migration we will have ever completed since, perhaps, the creation of Denali from the humble beginnings of ShowFlow and Site Builder.

I'm going to introduce each of these concepts and talk about why we are doing it, and why we hope that these form the new foundations for SuiteCommerce for years to come. However, at the time of writing this (2019.2) we have not fully migrated everything over to the new architecture. In other words, you are not mandated (again, at least at the time of writing) to use them, but you should certainly learn about them, look at the code, and make a start. In some cases there will be backwards compatibility, and in others there will be a deprecation process. In either case, let me encourage you to make the switch.

TypeScript

We are in the process of migrating the JavaScript in SuiteCommerce over to TypeScript. As of this release, we have done an initial migration of all frontend JavaScript so that it follows the syntax guidelines; over time we may do more refactoring or optimizations to it. As for the backend, the process of converting SuiteCommerce SuiteScript is incomplete as it is a bit more complicated, not least because we are also taking the opportunity to rewrite it to use SuiteScript 2.0.

For the time-being, this code has been separated out in the source — take a look at the Backend > SC directory, and you'll files for the cases functionality, as well as the order history.

For the uninitiated, TypeScript is an open source language created and maintained by Microsoft that is a superset of JavaScript — it looks and feels like JavaScript but it has a lot of 'syntatic sugar' to make working with JavaScript that little bit sweeter. It's called TypeScript because of the high value put on static typing, which is something that JavaScript lacks. In my opinion, it kinda looks and works like a hybrid of C# and JavaScript.

Here are some of the features:

  • You write in TypeScript and then it compiles down in JavaScript, so there's no worries about interoperability with other code
  • TypeScript contains a number of new concepts and patterns that are designed for complex applications that want to scale
  • You can also use more modern features of ECMAScript without worrying about compatibility because it will be transpiled to your specified older version
  • Built-in bug detection in your IDE enhances code quality and agility by performing error checking at pre-compile or compile time (ie in your IDE or CLI) rather than at runtime (ie in your browser)
  • Static types make the code more readable by capturing intention at the time (eg what a function expects in and what it will return)
  • Code completion and other goodies in your IDE provide active hints about what you should write next
  • If you don't know how to build something in TypeScript, you can just use JavaScript instead as it's perfectly valid

There are a whole lot more benefits to be had by using TypeScript, which is why we have decided to migrate to it.

If you are a SuiteCommerce Advanced developer, you will see that all of the SCA JavaScript modules are now written in TypeScript. Note, however, that the use of TypeScript is not mandatory. As I said above, TypeScript compiles down into JavaScript so that each file you create will have a corresponding .ts and .js file for it. Therefore: valid JavaScript is valid TypeScript. You may continue to write plain JavaScript in your TypeScript files if you wish.

However, we consider now a good time to get going in the process of learning how to use it — training courses are typically 4-5 hours long. For most developers, working with TypeScript will probably feel like learning a new language, so as developers you can go at your own pace. If you've worked with C-languages or Java before, you'll probably get up to speed quite quickly.

Finally, before closing this out I want to point out that while we are introducing TypeScript to the codebase, we have only integrated it into the core SuiteCommerce Advanced code. In other words, TypeScript is not supported in the extension developer tools.

Read more about TypeScript here.

SuiteScript 2.0

The latest major update to the SuiteScript language has been available for use within the NetSuite ecosystem in general for a while, and we've also talked about how you can use it in the context of your web store (just as long as you put it in your external scripts). As of 2019.2, we're pleased to say that it is now available natively throughout the SuiteCommerce Advanced bundle and that we have started the migration process.

SuiteScript 2.0 is something we've touted the benefits of before, for example:

  • Modularity — you'll already be familiar with AMD, and SuiteScript 2.0 takes full advantage of it with code broken down into individual modules and called when necessary with requireJS
  • Efficiency — almost all functions are accessed as methods within modules, which are not loaded into the global scope at runtime, and there are also map/reduce scripts which have been shown to very performant for long-running batch tasks
  • Modern — it runs ECMAScript 5.1 so you can now take advantage of things like asynchronous calls and promises (the SuiteScript 2.1 beta supports ECMAScript 2018)

In short, because you're already familiar with working with modern, modular JavaScript, you'll find yourself feeling very comfortable around SuiteScript 2.0 — there are just some new APIs to learn. Helpfully, there is some documentation in the help center to help you; for example, check out the SuiteScript 1.0 to SuiteScript 2.0 maps, which will help you reconceptualize how to work with backend SuiteCommerce code.

Keep in mind that you can also use TypeScript in your SuiteScript 2.0 SCA files, as they'll get transpiled into regular old JavaScript before they are deployed up. If you want to get sense of what this happy marriage looks like in the 2019.2 release, head on over to the source code for a look at the Case and OrderHistory modules, specifically the SuiteScript.

Finally, note the following:

  • SuiteCommerce will continue to support SuiteScript 1.0 for the time-being, but the plan is to eventually phase it out
  • You cannot mix SuiteScript versions in the same module
  • SuiteScript 2.0 is not currently supported by extensions
  • SuiteScript 2.1 is currently in beta but you can opt-in to use it in your SCA SuiteScript files

As we migrate to SuiteScript 2.0, we will be adding commerce-specific modules to the SuiteScript 2.0 API. Keep on an eye on the N/commerce module namespace for future updates.

SuiteCloud Development Framework (SDF)

I mentioned SDF in my 2019.1 announcement post and I'll mention it again here. Last time, I mentioned that we were laying the foundations for its use and now the time has come for you to also make the move towards, should you want to.

To confirm, however: it is still not a requirement to use SDF to customize your site. Instead, it is instead a recommendation for extension developers who want to distribute their extension outside of their instance. Therefore, if you're one of our commerce partners, or on an independent contractor who owns the code they write, it's definitely an approach you should consider.

To summarize, the benefits are:

  • They contain all of the NetSuite objects required for the extension to function, such as custom fields and records, thus ensuring your customizations are 'complete'
  • Feature detection to ensure customizations can only be installed on accounts that will support them
  • Script execution events that can fire, for example, before and after installation of the bundle

Accordingly, some knock-on effects of these are:

  • Easier sharing and deployment to other environments and NetSuite instances
  • Easier sharing within your own development team
  • Better support for version control

Our extensions team has migrated all of their extension code over to SDF and they are in the process of converting everything to TypeScript. While you won't notice this when you install our extensions, we encourage you to join us! It's the future!

Code Style

The leading-comma style (also known as 'comma-first') was a syntactic style we adopted since the early days of SuiteCommerce Advanced. However, as of this release, we are changing styles to the more 'traditional' trailing-comma style. In other words, instead of putting the separating comma at the start of the next line, we will putting it at the end of the previous line. There are numerous reasons for this but we agreed that it is more industry-standard, works better in IDEs, and works better in version control systems.

Extension Framework

Of course, it's not just TypeScript, SuiteScript 2.0, and SDF changes in the latest release, we've also made some changes to the extension framework. Some of them are code changes, and some of them are architectural.

Error Messaging Method

You may remember when we experimented with new components from the previous release, we created an extension that added a field that required validation. Part of that validation is surfacing an error message to the user to let them know what went wrong — for that we used the showError() method, which is bound to the Backbone view class.

Now, in 2019.2, you can instead use the showMessage() method, which is bound to the visual components (such as the layout, PDP and PLP components), like this:

var PDP = container.getComponent('PDP');
PDP.showMessage({
  message: 'Enter a valid quantity',
  type: 'error',
  selector: 'Quantity',
  timeout: 10000
})

Message and type are the only required parameters, but you can also optionally specify a location for it to render, and a time limit for how it should show for before it fades out. In my example, I have specified that I want to show an error message inviting the user to enter a valid quantity on a PDP page. Note that the specified selector is not a full jQuery selector; instead the code will first search the DOM for elements with a data-view attribute matching the string, and then for elements witha matching data-cms-area attribute.

Accordingly, this is the best practice for surfacing messages of all kinds (not just errors) — so please use this in your code from this version onwards.

Version Targeting for Themes and Extensions

As extensions and themes mature, it is entirely possible that some sites will lag behind the latest release of SuiteCommerce and SuiteCommerce Advanced and that may prove problematic for extensions and themes. As we introduce new features in new releases, it is important that site administrators of older sites cannot add new extensions or themes to their site that will not work because they depend on components or methods available in a release their site doesn't support.

Starting in the 2019.2 version of the extension manager, checks will be performed on the list of available extensions and hide those that are marked as incompatible with the selected site. To take advantage of these checks, extension developers will need to specify compatible versions in their extensions' manifest files.

In addition to the text property target in manifest.json, which lets developers specify which product the theme/extension is for, the developer may now pass an object to a new property called target_version specifying which versions of each product it supports.

For example:

"target_version": {
    "SCA": ">=19.2.0",
    "SCS": ">=19.2.0"
},

This object tells the extension manager that the extension can only be used with SuiteCommerce and SuiteCommerce Advanced sites running 19.2.0 or newer. Note the syntax — specifying only 19.2.0 would tell the extension manager that is available sites running version 19.2.0 exactly.

If you choose not to use this functionality, you can leave it blank (which implies no restrictions/target) or not declare the target_version property at all. However, if you do decide to use it, it's important to read the documentation on the new syntax.

Once this extension has been deployed to NetSuite, a field in the record for that extension will be populated with the object you specified in your manifest. When a user comes to activate the extension on a site, they will only see themes and extensions that are compatible with their site's version. In other words, incompatible extensions will be hidden and not show up as possible targets for activation.

A knock-on effect of this is that if you manage multiple sites across different versions, you can more easily manage different versions of your extensions. In other words, consider this: prior to this release, when you deploy an extension all versions of your sites see one extension and the old version is effectively 'lost'. Now, there is a remedy.

When you come to next update your extension, specify target_version data in your manifest file and then incremement the version number. For example, put "target_version": {"SCA": "~19.2.0"} to specify that this version is only applicable to sites running 19.2.x (ie 19.2 and its minor versions). Now, when it comes to activation, the extension will be shown as an available update to sites running 19.2.x but no others. Your 19.1.x sites and earlier (and 20.1.x and later for that matter) will not see it, and you are free to continue activating/deactivating using the old version of that extension on those sites.

Just keep in mind that this can complicate matters for you locally. For example, if you only ever maintain one local version of the code, then it could become problematic should you ever need to push an update to an old version of the code. However, if you use version control systems (such as Git) these should be easy to manage (eg with forks/branches).

In other words, if you push a new version of an extension up to the NetSuite that is incompatible with the specified target version, they will not see the new version but can continue to perform activations with the old version of the extension. This perfect for people who operate more than one site from their account.

Improved Feedback from Extension Manager Activation Errors

This has been a popular request and we have listened: we have improved the feedback the extensions manager gives when a theme fails to activate. Specifically, we know that a number of you were annoyed at ambiguous error messages when you have supplied invalid Sass to the compiler (eg messages about not being able to find or copy some of the images).

This update improves the feedback now so that it will be more descriptive. We have also made general improvements to the feedback so that if a specific job fails, this is surfaced so that it is easier to track down the cause of the problem.

Remember, the extension manager is a separate bundle from the core SuiteCommerce and SuiteCommerce Advanced bundles, so anybody can upgrade their account's SCEM bundle to the latest version to take advantage of these benefits.

Important New Features

OK, we looked at all the techy stuff, so let's talk about all the cool features in 2019.2 I think are particularly relevant for developers.

Site-Level Page Layouts

In 2019.1, we introduced the concept of page types and layouts. One of the important new features this change introduced was the capability for content managers to change the appearance of a particular page using the site management tools using pre-defined alternative templates that their developer has provided.

One limitation of this feature at the time was that changes to pages could only be done on a per-page basis, which meant, for example, that you could change the layouts of individual product detail pages one at a time, but you couldn't change all PDPs at once. We are pleased to say that, as of 2019.2, this limitation has been lifted and we have introduced the capability for content managers to set the default layout for a page type that will affect all instances of that type at once using the site management tools.

Now, once you've changed the 'global' layout of a particular page type, you can still override it in on a per-page basis, just like before, if you like. What we're effectively introducing is the ability to set the default template for a page type using the site management tools.

Options Object

On the subject of page types; we have now added support for an options object to pass through to the view constructor when using the page type component's registerPageType() method. Handy!

Personalized Catalog Views

If you remember, this is something we talked about back in March, so we're very pleased to include it in this release. It's an example of a customization that developers have been frequently asked to add to sites by their customers, so we're pleased to add this to SuiteCommerce's 'out of the box' offering.

To summarize, this functionality lets you split your customers and inventory up in segments and then decide which groups of customers can see which groups of items. It's a commonly requested feature for both B2B and B2C organizations, due to the wide-ranging applications that it has.

If you're unsure of what you could use this for, our documentation team have helpfully put together a number of useful examples that you can use on your web store. For example:

  1. Exclusive items for VIP customers — a subset of your items only visible to a select group of users (all other items are available to all users)
  2. Different catalogs for different locations — depending on where a customer is from, they will see a group of items specific to that location (no customer sees all items)
  3. Items available only to certified customers — customers gain access to certain product lines after they have provided the required documentation/licenses

In addition to these use cases, I think it also provides a solution for a lot of common requirements around microsites. That term means a lot of different things to a lot of different people, but one of the common requirements we receive around it is the concept of item exclusivity. With this functionality, you are able to clearly demarcate your inventory and customers into groups, and then map the two types together as you wish.

SuitePromotions: Qualifying Item Quantity

A common enhancement request we have had regarding the promotions engine is to introduce a concept of a 'qualifying item quantity' to a promotion's trigger. Previously, a merchandiser could, for example, set up a promotion so that once a customer adds a particular item to the cart, they would get a discount regardless of the quantity of the trigger item. Now, merchandisers can now specify a quantity value that either sets a minimum amount the user needs to buy, or to act as a multiplier indicating how many units the user must purchase before the promotional benefit repeats.

To give you an idea, here are some ideas for minimum quantity promotions:

  1. 25% off socks when you buy a minimum of 100 pairs of shoes
  2. 10% off your order if you buy a minimum of 500 accessories
  3. Free shipping if you buy at least 500 flyers

For the incrementally repeating promotions, compare these two promotions:

  1. Buy at least two dresses and get 25% off a bag
  2. For every two dresses you buy, get 25% off a bag

In the first example, our promotion will not repeat the discount incrementally, but in the second it will. In other words, the first promotion does not care whether a customer buys 2, 10, or 100 dresses — they will only ever receive a discount on one bag; in the second, the promotion will apply the discount multiple times, depending on how many dresses and bags they buy.

Finally, the discount target is not just limited to items; ie, while these examples apply discounts to items using item triggers, you are free to specify that the promotion's target is a different area of the transaction, such as the order in general or shipping costs.

Minor Enhancements

Don't worry, there are more new features included in the release, but I figured I'd move onto some smaller ones and keep things focused on the sorts of things that affect commerce developers.

Website Deactivation

Next up, we have an important new feature. As NetSuite accounts typically have a low limit to the number of web stores they can have active at once, a number of customers expressed problems with decomissioning (deleting) old sites (whether production or development ones) due to the high number of dependent records.

At the moment, we don't have a solution that can make deleting a site record with so many dependent records possible, but we have introduced the concept of site deactivation. In the NetSuite context, this means that we have added functionality to web site setup records that is common on many NetSuite records: an Inactive checkbox.

Now, when you edit a website setup record, you can use this checkbox to deactivate that site. After the record is marked as inactive, it won't count towards an account's provisioning limit for web store licenses, meaning that the account is free to create a new web site setup record for a new site.

When you deactivate a site record, a number of processes run that make the site dormant, for example:

  • Any associated promotions, shipping rules, domains, shipping items, etc, are all updated to reflect the site's 'inactive' status
  • Any associated web store domains will be unreacheable via a web browser — and this includes all their related services such as APIs, SMT content, WSDK, etc
  • The site's search index and all its caches are cleared

In other words, it's a pretty serious thing to do so you must be sure that it is something you want to do. If you want to take a site offline temporarily (eg to run maintenance) then you should consider using the provided checkbox for that.

Phasing Out of Legacy Email Templates

Since 18.2, we've supported the concept of 'system email templates' in SuiteCommerce and SuiteCommerce Advanced. In 19.1, we provided some enhancements and ramped up our messaging that we were planning to phase out support for older types of web store emails. As of 19.2, customized text groups and web store email templates have been phased out.

You should have already migrated your site's emails to system email templates (although fulfillment emails may still use web store email templates).

As a reminder, system email templates are highly customizable and definitely an interesting avenue for developers to get stuck into.

Extensions Updates

Remember that a lot of site features are now delivered as extensions, which are free and publicly available to all SuiteCommerce and SuiteCommerce Advanced customers. They operate on their own separate release cycle, so you should always keep an eye on our What's New section, in particular the extensions release notes page.

Final Thoughts

As I said, there's more to this release than just this blog post — all I'm doing here is prioritizing the parts of the release I think most relevant for commerce developers. We also have enhancements to the merchandise hierarchy, for example, as well as a new SuiteAnalytics workbook for search that shows you the top search queries with results and another without results.

As always, I strongly recommend you read the full release notes.

Documentation Links