Customizing Products with Scripts Using Action Records and Functions

Action records let you customize products using scripts that can automate repetitive tasks or perform advanced tasks, which would otherwise require multiple manual steps. For example, you can use actions to automatically set a series of answers on the product interface or create items required by the configuration.

In custom scripts stored in action records, you can use functions from the NetSuite CPQ Configurator library to provide advanced or custom interactions, and to read or modify data on the server. Some examples of these functions include getValue(), showMessage(), and getData().

Actions become active if their rule matches the answers users select on the product interface and are processed according to their sequence number—those with a lower sequence number run before actions with a higher sequence number.

However, NetSuite CPQ Configurator distinguishes between before-event and after-event actions, depending on when they're verified and processed (if active) compared to the rest of building blocks (questions, answers, additional items, and so on). Every time a user makes a selection or enters information on the production interface, the system verifies the building block rules and performs the related tasks in this order:

1. Before-event actions according to their sequence number.

2. Other building blocks such as questions, answers, materials, and so on.

3. After-event actions according to their sequence number.

After all building blocks are verified and processed, the product interface refreshes to display any changes.

After-event actions are those with the Run as after-event box checked. All other actions are considered before-event. Before-event actions run before after-event actions, even if they have a higher sequence number.

Actions are either client-side or server-side. Each type supports different sets of functions depending on whether they run on the client or the server. For more information, see Using Client-Side and Server-Side Actions.

The action record includes a code editor for writing and editing code. The code editor provides suggestions and documentation as you type. For more information, see Supported Code Writing.

If you frequently use the same code in multiple action records, you can create common actions to share code across actions and products and keep it organized and consistent. For more information, see Sharing Code with Common Actions.

To create an action:

1. In NetSuite, go to CPQ > Configurator > Product Maintenance.

2. Click Edit next to the product you want to modify.

3. On the Actions subtab, click New CPQC Action.

4. Enter a descriptive name for the action.

   This name is displayed under Actions in the Audit menu of the product interface.

5. In the Code field, enter a unique identifier for this action.

   You can use an abbreviated version of the name as the code to identify the action. The code must contain only uppercase letters, numbers, and underscores.

6. Provide a sequence number to determine the order in which the action is processed.

   You can enter a negative or positive number, for example, -2 or 5.

7. If the action should be verified and processed after all other building blocks rules, check the Run as after-event box.

   For example, you can use this option for actions that needs to process the updated material list.

8. To perform this action only the first time the rule condition is met, check the Run only on first match box. The action will only run again if the rule condition becomes false and then true again.

9. In the Rule field, provide the condition that determines whether the action will run.

   Enter question and answer codes separated by a forward slash, for example, A/1. Use operators to combine multiple conditions, for example, A/1&B/2. For more information, see Activating or Hiding Building Blocks with Rules.

10. (Optional) To include an additional rule in the action rule, select a rule category. The action will run only if both its rule and the rule category match answers selected by users on the product interface. For more information, see Working with Rule Categories.

11. To define the tasks that the action will perform, three options are available:

    • In the code editor, enter the NetSuite CPQ Configurator functions.

    • In the Add Function field, select the NetSuite CPQ Configurator functions you want to add to the code editor and follow the onscreen instructions.

    • In the Common Action field, select a common action shared across all products and use its code.

      Note:

      If you use a common action, any code entered in the editor will be disregarded. For more information, see Sharing Code with Common Actions.

    You can combine manually entered JavaScript functions with those selected in the Add Function field.

12. Click Save.

Sharing Code with Common Actions

If you frequently use the same code in multiple action records, you can create common actions that are shared across actions and products. This approach lets you easily maintain the code, ensure consistency, and promote code reuse.

Note:

If you want to share common actions across multiple products, make sure question and answer codes for functions are the same.

After creating a common action, assign it to an action record using the Common Action field.

To create a common action:

1. Go to CPQ > Configurator > Common Actions.

2. Click New CPQC Common Action.

3. Provide a name for the common action.

4. To define the tasks that the action will perform, two options are available:

   • In the code editor, enter the NetSuite CPQ Configurator functions for the tasks you want to perform.

   • Use the code writing support:

     1. In the Product ID field, select the product from which you want to source question and answer codes for the NetSuite CPQ Configurator functions.

     2. In the Add Function field, select the functions you want to add to the code editor and follow the onscreen instructions.

5. Click Save.

Supported Code Writing

You can write and edit code using the integrated editor on the action record. As you type, the editor automatically displays a popup window with suggestions and documentation that guide you through the scripting process. Short annotations help you identify the suggestion type. For example, annotations can identify a suggestion as a function or a keyword.

You can scroll through the list of suggestions and select the one you prefer. When moving through the list, the suggestion popup displays documentation for each NetSuite CPQ Configurator function. If you select a function, the editor automatically adds a code template with parameter placeholders.

You can move through the placeholders by pressing Tab and replace them with business information. If you want to hide the suggestion popup, press Esc. To bring it back, press Ctrl+Space.

Using Client-Side and Server-Side Actions

Two types of actions are available—client-side and server-side. Client-side actions contain scripts that run in the web browser, whereas server-side actions run on the server and can read or modify data on the server. Depending on their type, actions can work with different sets of functions.

The functions can be categorized as follows:

• Universal functions – Work with questions and answers. For example, getValue() and setValue().

• User interface functions – Work with and change the look and feel of the product interface. For example, showMessage(), customizeUI(), and getProgress().

• Window interaction functions – Work with the parent window. For example, queryParent() and sendMessage().

• Status functions – Work with the NetSuite CPQ Configurator statuses (startup, running, final). For example, submitConfig().

• Database functions – Read and write data to the database on the server. For example, getData(), getItemPrice(), and createRecord().

Only server-side actions can work with functions that make requests to the database. Client-side actions can't access the database directly, but they can request information by calling server-side actions. Both server-side and client-side actions work with the functions that interact with questions and answers. Client-side actions can also work with functions that interact with the user interface, the parent window, and statuses.

The following table sums up the available function types for client-side and server-side actions.

Client-Side Actions	Server-Side Actions
Universal functions	Universal functions
User interface functions	Database functions
Window interaction functions	—
Status Functions	—

User interface functions, window interaction functions, and status functions are considered client-side functions because they only work in client-side actions. Database functions are considered server-side functions because they work only in server-side actions. For more information about the function types, see List of Functions.

To create a server-side function, check the Run on server box on the action record. Actions without this option enabled are considered client-side.

Both server-side and client-side actions can be written in JavaScript ES5 or ES6. When activated by their rule, server-side and client-side actions run synchronously. Server-side actions can also run asynchronously when called by the runAction() function from a client-side action. Asynchronous functions must always be stored in client-side actions.

Extensive server-side actions must be called asynchronously using the runAction() function so that the upcoming actions don't freeze the browser window by waiting for its response. In the rule of a server-side action called using runAction(), you must enter X(*/*) —the always false operator—because the action isn't activated by answers selected by users on the product interface.

The following examples show how to call a server-side action asynchronously from a client-side action:

            runAction('ACTION_CODE').done(callback); 

          

            (async function() {
    //code 
    await runAction('ACTION_CODE');
    //code 
})(); 

          

In the first example, the callback function runs after the server-side action has completed its task. For more information about using the runAction() function, see Performing Server Requests in Batches.

Establishing Client-Server Communication

Server-side actions can't access the window object to obtain information from the client, and client-side actions can't access the server. Client and server-side actions can share information through the following resources:

• Questions and Answers

• The Scratchpad Variable

• Function-Generated Tables

• QTables

Questions and Answers

Client-side and server-side actions can store and obtain information from questions and answers through universal functions, such as setValue() and getValue(). After submitting the configuration, this information is saved to the configuration record. With this method, you can share information from client to server and the other way around. Use this method to share a small amount of data that will be displayed on the product interface or used in rules.

For more information about implementing questions and answers in client-server communication, see Transferring Data Using Questions and Answers.

The Scratchpad Variable

The scratchpad variable is a temporary object available for both client- and server-side actions. In the scratchpad variable, you can store any data type and transfer it from client to server and the other way around. After submitting the configuration, the scratchpad variable is cleared and isn't saved to the configuration record. Use this option for large amounts of temporary data that don't need to be stored in the configuration record.

The following example shows how to save data obtained from the server to the scratchpad variable.

              scratchpad.companyname = customer.companyname; 

            

The following example shows how to save data obtained from the client to the scratchpad variable.

              scratchpad.sku = prompt('Enter the item SKU'); 

            

For more information about implementing the scratchpad variable in client-server communication, see Transferring Data Using the Scratchpad Variable.

Function-Generated Tables

Client-side and server-side actions can store and obtain data through function-generated tables (formerly called CE-generated tables) because they act like variables. However, data must have a table-like structure in the form of an array of objects where each object is a row, and each key of the object is a column. Use this option to share data from the server to the client when you work with input box popup table answers (formerly called picklists). To share data from the client to the server, use the scratchpad variable.

For more information about transferring data with function-generated tables, see Transferring Data from Server to Client with Function-Generated Tables.

QTables

Client-side and server-side actions can store and obtain information from qTables because they act like variables. Data must have a table-like structure. Use this option to share data from the server to the client when you need to display the information on the product interface as a table. To share data from the client to the server, use the scratchpad variable.

For more information about transferring data with qTables, see Transferring Data from Server to Client with QTables.

Related Topics

• NetSuite CPQ Configurator Products
• Activating or Hiding Building Blocks with Rules
• Working with the Product User Interface
• Calculating the Final Pricing for the Configurable Item
• Including Additional Items Related to the Configurable Item
• Creating Work Orders for Configured Items
• Creating Items Required by the Configuration
• Creating Records Required by the Configuration
• Setting Transaction Body and Line Fields Based on Configuration Data
• Working with Product Configurations
• Including Additional Conditions in Rules and Actions with Predefined Answers
• Working with Configurable Subscriptions

General Notices