Services and Backend Models
To handle data transactions with NetSuite, SuiteCommerce Advanced (SCA) provides multiple endpoints that enable access to data stored in NetSuite records. How SCA handles these RESTful services depends on your implementation. For details about the services architecture for earlier versions of SCA, see Architecture Overview (Pre-Vinson).
This section explains the service and backend model architecture for the Vinson release of SCA and later. Services handle communication between the frontend SCA application and the backend models that connect to NetSuite. With the Vinson release, these services (.ss files) are auto-generated and call Service Controllers. These Service Controllers and other files maintain code common to all services within a centralized location, as described in the detailed descriptions that follow.
The Vinson release of SCA is backward-compatible with the pre-Vinson services. To enable backward-compatibility, you must edit the associated module’s ns.package.json files. See Using Pre-Vinson Services with Vinson Release or Later for more information.
The files and functionality described in this topic apply to the SCA components that are coded in SuiteScript 1.0. The following content does not apply to the components that have been migrated to SuiteScript 2.0. When migration to SuiteScript 2.0 nears completion, more information will be provided for the migrated components. See Commerce Migration to SuiteScript 2.0 for more information about the migration progress.
The following components make up the backend service architecture. The following sections provide more detail about each component:
SC.EventWrapper
This file contains centralized, extensible Before and After Event listening capabilities plus extension capabilities for use by all service methods. SC.EventWrapper.js is located in the SspLibraries module.
ServiceController
This file contains the common logic used to operate any service. ServiceController contains the handle() method, which executes the method related to the HTTP requests identified in any [Module].ServiceController. ServiceController.js is located in the SspLibraries module.
ServiceController contains the required try/catch block to ensure that any errors are passed back to the frontend application and are handled by the ErrorManagement module. The ServiceController module also extends SC.EventWrapper and references validation methods declared in ServiceController.Validations.
As of the 2019.2 release of SCA, all instances that extend ServiceController are located in one of two places. For modules utilizing SuiteScript 2.0, these instances can be found in SC_xxx/Backend/SC/. If customizing using SuiteScript 1.0, these can be found in the SuiteScript folder of the module during development. When you deploy to the server, the specific [Module].ServiceController code writes to the ssp_libraries.js file.
[Module].ServiceController
One [Module].ServiceController exists per service. This file processes requests for a specific service and extends code within ServiceController. Each [Module].ServiceController executes the proper functions based on the HTTP actions (GET, POST, PUT, DELETE) initiated by the frontend framework, which are passed through the associated .ss file. [Module].ServiceController can also call methods on any necessary backend models.
Each [Module].ServiceController can include an options object, which details any permissions and validations needed for the HTTP methods. Each service requires a unique [Module].ServiceController.
[Module].Service.ss
This file handles communication between the frontend SCA application and the associated controller ([Module].ServiceController). The .ss file is automatically generated in the services folder of the local distribution. After you deploy your site, the .ss file exists in the services folder of the proper SSP Application. One .ss file exists per service.
Each [Module].Service.ss file is also responsible for passing data from the backend model to the frontend model or collection that initiated the HTTP request. This data is passed as a JSON object from the backend model to the .ss file through the associated [Module].ServiceController.
The following example shows the auto-generated .ss file for the Account Login service. This file only calls the [Model].ServiceController associated with the service as defined in the ns.package.json file.
//Autogenerated service function.
function service(request, response)
{
'use strict';
require('Account.Login.ServiceController').handle(request,response);
}
When you deploy your site, the autogenerated-services object of the associated module’s ns.package.json file signals the developer tools to auto-generate each .ss file and associate it with a specific service controller. Failure to include this code will result in an error and the .ss file will not generate. If you want to use pre-existing (pre-Vinson) services with a Vinson implementation, you must register the service in the services section of the associated module’s ns.package.json file. See Using Pre-Vinson Services with Vinson Release or Later for more information.
Backend Model
The backend model contains methods that access NetSuite records by calling the SuiteScript API. The Backend Model architecture and logic have not changed with the Vinson Release of SCA.
ServiceController.Validations.js
This file contains the extensible validation methods for requests common to all services. This file is located in the SspLibraries module.
Each feature or module in SCA generally defines the services and backend models needed to access the required data. The Cart module, for example, defines the services and backend models for accessing items currently in the cart. Each module’s [Module].ServiceController files and backend models are stored in the JavaScript directory of each module.
When you deploy SCA, the gulp tasks auto-generate the required .ss files and deploy all of the services to the SSP application. The gulp tasks also add backend models to the ssp_libraries.js file. For more information, see The ssp_libraries.js File.