Services and Backend Models

This topic applies to

Applies to

SuiteCommerce Advanced

To handle data transactions with NetSuite, SuiteCommerce Advanced provides multiple endpoints that enable access to data stored in NetSuite records. How SuiteCommerce Advanced handles these RESTful services depends on your implementation. For details on services architecture when implementing earlier versions of SCA, see Architecture Overview (Pre-Vinson)

This section explains the service and backend model architecture for Vinson release of SuiteCommerce Advanced and later. Services handle communication between the frontend SuiteCommerce application and the backend models that connect to NetSuite. With Vinson release, these (.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 below.

Note

The Vinson release of SuiteCommerce Advanced is backward-compatible with pre-Vinson services. This requires editing the associated module’s ns.package.json files. See Using Pre-Vinson Services with Vinson Release or Later for more information.


The following components make up the backend service architecture:

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.

Note

All instances that extend ServiceController are located 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 SuiteCommerce 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 via 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);
}

Note

When you deploy your site, the autogenerated-services object of the associated module’s ns.package.json file signals the dev 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 (preVinson) services with a Vinson implementation, you must register the service in the services section of the associated module’s the 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 SuiteCommerce Advanced.

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 SuiteCommerce Advanced 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 SuiteCommerce Advanced, 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. See The ssp_libraries.js File for more information.