SuiteScript2 (SS2) Services for SuiteCommerce | Basics of Use

a computer keyboard sitting on top of a desk

This article covers the basics of using SuiteScript2 (SS2) service files in your extensions for SuiteCommerce. A request is made to a service file when certain functions are run on Backbone Models in the front end.

Need a refresher on the basics of SuiteScript 1 vs. SuiteScript 2? Checkout the tutorial article What is SuiteScript?

Adding a Service to Your SuiteCommerce Extension

Ideally, select the “SuiteScript2” option when running “gulp extension:create”. You can, however, always manually add the file(s) later if needed by simply adding .ss files to your “SuiteScript2” folder and Backbone Model files to your “JavaScript” folder as needed.

“Calling” or “Making a Request” to Your Service

An SS2 service is called when the “fetch”, “sync”, “save”, or “destroy” function is called on a properly formatted Backbone Model. We will ignore “sync” here, and you likely should ignore it too.

“fetch”

Makes an HTTPS “GET” call. Use fetch anytime a “GET” request is desired.
The response data from the call will be set on the Model as “attributes”.
Data can be passed to the service as part of the request parameters.
Here is a "fetch" code example:

new ContactManagementMyAccountModel().fetch({
    data: {
        getRole: 'T'
    }
}

Learn more about the "fetch" Backbone Model.

“save”

Makes an HTTPS “POST” or “PUT” call. Use save anytime a “POST” request is desired.
The response data from the call will be set on the Model as “attributes”.
Data can be passed to the service as part of the request parameters.
Here is a "save" code example:

this.model.save({
   action: 'update',
   userId: userId
});

Learn more about the "save" Backbone Model.

“destroy”

Makes an HTTPS “DELETE” call. It is unlikely you will ever need to use destroy.
Data can be passed to the service as part of the request parameters.
Here is a "destroy" code example:

this.model.delete({
   action: 'remove',
   userId: userId
});

Learn more about the "destroy" Backbone Model.

“parse”

One more important function. “parse” is a native function that can be overridden. It allows the user to manipulate the request response before the data is set on the Model.
Learn more about the "parse" Backbone Model.

Note: While you could technically overwrite the “fetch”, “save”, and “destroy” functions for your model this will likely interfere with calling the service, so be careful in doing so.

Setting Properties on the Model

In order for a Model to call a service file, the following properties need to be set on the Model:

The “urlRoot” and/or “url” properties must be set. This property points to the service file using a relative path or an absolute URL. The “urlRoot” is set by generated when the Model file is created by the gulp command. It should look something like:

urlRoot: Utils.getAbsoluteUrl(
            getExtensionAssetsPath("Modules/CustomStoreLocator/SuiteScript2/CustomStoreLocator.Service.ss"),
            true
        )

Setting Up the Service File

For the service to work, the file needs to be set up in the following ways:

NOTE: These requirements only apply to service files, not Suitelets.

The file name needs to end in “.ss”.
The file must be formatted like other Suitescript 2.x files. For example:

/**
* @NApiVersion 2.x
* @NModuleScope Public
*/
define(['N/record','N/runtime'],function (record,runtime) {
    "use strict";
	
	function service(ctx) {
	
		var responseObj = {};
		var params = ctx.request.body ? JSON.parse(ctx.request.body): {};
		
		var getParams = ctx.request.parameters;
		
		try{
			var userObj = runtime.getCurrentUser();
			
			if(getParams.getRole == 'T'){
				responseObj.role = userObj.role;
			}
			
		}
		catch(e){
			responseObj.error = e;
		}
		
		ctx.response.write(JSON.stringify(responseObj));
	}
	
    return {
        service: service
    };
});

The file must return the entry point “service”, which must be mapped onto a function (of any name).
The sole argument of the service function, often written as “context” or “ctx”, includes important info such as the incoming data and type of call (GET, POST, etc).
The service file writes data back to the model using

ctx.response.write(JSON.stringify(responseObj));

This method should only ever be called once per execution of your service.

Set Up Service File in NetSuite File Cabinet

Like any other SuiteScript, a service file will not run until set up correctly in the NetSuite File Cabinet.

Deploy the extension to get the file into the backend.
Navigate to the “live” service file located here: Commerce > Hosting > Website Hosting Files > Live Hosting Files > SSP Applications > NetSuite Inc. - SCA 2021.2.0 (or whatever version you are using) > Development2 > extensions – then dig down to find your extension’s service file.
Once you have the file record open, enable Permissions on the file. Be sure to “execute as” a role that has the needed permissions.
Save the file updates. Your service file should now be usable!

Updating the Service File

Any updates to your service file must be made be either deploying your extension again or by manually editing the file record (this second option is much easier).

Author: Sam Gagliardi

Got stuck on a step in this article?

We like to update our blogs and articles to make sure they help resolve any troubleshooting difficulties you are having. Sometimes, there is a related feature to enable or a field to fill out that we miss during the instructions. If this article didn't resolve the issue, please use the chat and let us know so that we can update this article!

Oracle NetSuite Alliance Partner & Commerce Partner

If you have questions about how our team can support your business as you implement NetSuite or SuiteCommerce, feel free to contact us anytime. Anchor Group is a certified Oracle NetSuite Alliance Partner and Commerce Partner equipped to handle all kinds of NetSuite and SuiteCommerce projects, large or small!

SuiteScript2 (SS2) Services for SuiteCommerce - Basics of Use