Create a Service to Handle HTTP Requests

This topic applies to

Applies to

SuiteCommerce Advanced

Services handle HTTP requests sent by the frontend application to access backend models, which connect to NetSuite. Different releases of SuiteCommerce Advanced handle services with significant differences. This section explains how to create a service when implementing the Vinson release of SuiteCommerce Advanced or later.

Note

If using existing, customized services from previous implementations of SCA with the Vinson release, you can still use them without refactoring your custom code. Vinson offers backward compatibility with any services of previous implementations. See Using Pre-Vinson Services with Vinson Release or Later


With the Vinson release of SuiteCommerce Advanced, much of the logic required to operate a service is contained in a centralized location within the source files provided. However, you must still perform the following to create a custom service:

  • Step 1: Create a custom [Module].ServiceController

  • Step 2: Set up the Dev Tools to auto-generate the service and associate it with a service controller

  • Step 3: Customize your own validations (optional)

Step 1: Create a Custom [Module].ServiceController

Each service requires a unique [Module].ServiceController. You create this file, where [Module] is the module using the service. To create this custom ServiceController, perform the following:

  • Create a new [Module].ServiceController file in the SuiteScript folder of the module.

  • Define the custom ServiceController and dependencies.

  • Extend ServiceController.

  • Add any custom validation options (optional).

  • Add any HTTP methods as required for the service.

To create a new [Module].ServiceController file:

  1. Create a new file titled [Module].ServiceController.js, where [Module] is the module associated with the service.

  2. Place this file in the SuiteScript folder of the module.

    For example, if you are creating a new login service for the Account module, you would title it Account.Login.ServiceController.js and place it in your local Account/SuiteScript folder.

To define your custom [Module].ServiceController and dependencies:

  1. In your new [Module].ServiceController, define the specific ServiceController and any dependencies.

  2. Include ServiceController as a dependency

The following code defines the Account Login ServiceController and enables the service to access methods defined in ServiceController and Account.Model.

// Account.Login.ServiceController.js - Service to handle the login of a user into the system define( 'Account.Login.ServiceController' , [ 'ServiceController' , 'Account.Model' ] , function( ServiceController , AccountModel )

To extend ServiceController:

  1. [Module].ServiceController must extend ServiceController and include the name property. This property is used when listening to an event is needed. The value of the name property should match the name of [Module].ServiceController.

  2. Use the following example as a guide. This shows this extension with the name property.

    { 'use strict'; return ServiceController.extend({ name:'Account.Login.ServiceController'

To add custom Validation Options (Optional):

  1. If you need to define any validation options for the service, include these within return ServiceController.extend.

  2. Use the following example as a guide. This defines a requirement for the HTTP protocol to be secure before operating this service.

    , options: { common: { requireSecure: true } }

To add HTTP methods:

Within the object returned, define the functions required to handle the HTTP methods for the service. This code reads the HTTP method sent from the frontend (POST, DELETE, GET or PUT).

  1. For your [Module].ServiceController to function, you must declare each method in lowercase and it must match the name of the HTTP method being used.

  2. Use the following example as a guide. This defines what the service does on a POST request.

    , post: function() { return AccountModel.login(this.data.email, this.data.password, this.data.redirect) }

Using these examples, your custom [Module].ServiceController might look something like this:

// Account.Login.ServiceController.js - Service to handle the login of a user into the system define( 'Account.Login.ServiceController' ,[ 'ServiceController' , 'Account.Model' ] ,function( ServiceController , AccountModel ) { 'use strict'; return ServiceController.extend({ name:'Account.Login.ServiceController' , options: { common: { requireSecure: true } } , post: function() { return AccountModel.login(this.data.email, this.data.password, this.data.redirect) } }); } );
Step 2: Set Up the Dev Tools

With the Vinson release of SuiteCommerce Advanced, the dev tools automatically generates the required .ss service file. You must perform the following to successfully deploy your new services:

  • Include your new [Module].ServiceController in the ssp_libraries.js file.

  • Signal the dev tools to auto-generate your service and associate it with your new Service Controller.

To set up your new service controller:

You must edit the distro.json file to include your new [Module].ServiceController in the ssp_libraries.js file when you deploy your site.

  1. Open the distro.json file in the root directory of the SuiteCommerce Advanced source code.

  2. Create a new dependency within the Ssp-libraries object for your new custom Service Controller. For example, Account.Login.ServiceController:

    "ssp-libraries": { "entryPoint": "SCA", "dependencies": [ "Account.Login.ServiceController", ... ], }
  3. Save the distro.json file.

To auto-generate your [Module].Service.ss file:

You must edit the ns.package.json file of the module associated with the service. This file signals the dev tools to auto-generate your [Module].Service.ss file and associate it with a specific service controller.

  1. Open the ns.package.json file located in the module containing your new, custom Service Controller.

  2. In the autogenerated-services object, define the new .ss file and associate it with the appropriate Service Controller.

    , "autogenerated-services": { "Account.Login.Service.ss" : "Account.Login.ServiceController" }

    Note

    The autogenerated-services object may not exist in your implementation. If not, create the object and add the .ss files and Service Controller associations. Each .ss file must associate with one Service Controller.


  3. Save the ns.package.json file.

  4. Use the dev tools to deploy your services to your site.

    The dev tools will create Account.Login.Service.ss and associate it with Account.Login.ServiceController.js.

Step 3: Set Up Custom Validations (Optional)

As an option, you can extend ServiceController.Validations to create any custom validations for your services beyond those included by default. To set up custom validations, perform the following:

  • Create a custom Validations file and add custom validation logic.

  • Edit the distro.json file to include this new file as a dependency.

To create a custom Validations file:

  1. In the SspLibraries folder, create a new file titled ServiceController.Extend.Validations.js.

  2. Define this file and extend ServiceController.Validations.

  3. Add your custom validation logic.

    The following example depicts a typical custom validations file. This file extends ServiceController.Validations and contains custom logic to check validations.

    define( 'ServiceController.Extend.Validations' , [ 'underscore' , 'ServiceController.Validations' ] , function ( _ , ServiceControllerValidations ) { 'use strict'; _.extend(ServiceControllerValidations, { checkValidationGeneric: function() { // validation logic here... } }); });
  4. Set up the options object in any [Module].ServiceController using these validations. For example:

    , options: { common: { checkValidationGeneric: true } }

To set up the dependency in distro.json:

  1. Open the distro.json file in the root directory of the SuiteCommerce Advanced source code.

  2. Create a new dependency within the Ssp-libraries object for your new custom Service Controller. For example:

    "ssp-libraries": { "entryPoint": "SCA", "dependencies": [ "ServiceController.Extend.Validations", ... ], }
  3. Save the distro.json file and deploy using the dev tools.