Add Custom Button to Execute a Suitelet

This use case shows you how to add a custom button on a sales order form when the sales order status is Pending Fulfillment. When the button is clicked, a Suitelet is executed.

This project is available on the SuiteCloud Project Repository on Oracle Samples GitHub and include complete project customization setup with custom objects, unit tests, package file configuration, and more.

Note:

You can build Suitelets to do things like start a custom printing process or open a popup window to prompt the user for details to create a custom record related to the order. However, creating a Suitelet is not a part of this tutorial. Your Suitelet must already be developed and deployed. For more information about Suitelets, see SuiteScript 2.x Suitelet Script Type.

Customization Details

The customization for this use case includes:

• A script parameter (Suitelet Link) to specify the Suitelet link

• A user event script triggered on the beforeLoad entry point

Steps in this tutorial to complete this customization:

• Before You Begin

• Step 2: Write the Script

• Step 2: Create the Script Record

• Step 3: Deploy the Script

• Step 4: Create and Set the Script Parameter

• Step 5: Test the Solution

Before You Begin

The following table lists features, permissions, and other requirements necessary for performing this tutorial and implementing the solution:

Required Features	The following features must be enabled in your account: Server SuiteScript - This feature allows you to attach server scripts to records. File Cabinet - This feature allows you to store your script files in the NetSuite File Cabinet. Sales Order - This feature allows you to create, edit, and save sales orders (before fulfillment or payment). For more information, see Enabling Features.
Required Permissions	You will need a role with access to the following: Scripts - Edit access Script Deployments - Edit access Sales Orders - Edit access Transaction Forms - Edit access For more information, see NetSuite Permissions Overview
Other Requirements	You must already have a Suitelet developed and deployed in NetSuite. The custom button added in this tutorial opens the Suitelet in a new window.

Step 2: Write the Script

This script adds a custom button to the sales order form if the status of the sales order record is Pending Fulfillment. When the user clicks the new button, a window is displayed for the Suitelet.

Script Summary

The following table summarizes the script:

Script: Add Button to Execute Suitelet
Script Type	SuiteScript 2.x User Event Script Type
Modules Used	N/runtime Module N/log Module - This module is available to all scripts as a global object. However, you should explicitly load this module to avoid conflicts with other objects that may be named ‘log’.
Entry Points	beforeLoad(context)

For more information about script types and entry points, see SuiteScript 2.x Script Types.

The Complete Script

This tutorial includes the complete script along with individual steps you can follow to build the script in logical sections. The complete script is provided below so that you can copy and paste it into your text editor and save the script as a .js file (for example, sl_executeSuiteletButton.js).

If you would rather create your script by adding code in logical sections, follow the steps in Build the Script.

Note:

This tutorial script uses the define function, which is required for an entry point script (a script you attach to a script record and deploy). You must use the require function if you want to copy the script into the SuiteScript Debugger and test it. For more information, see SuiteScript Debugger.

Important:

This sample uses SuiteScript 2.1. For more information, see SuiteScript 2.1.

              /**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 * @NModuleScope SameAccount
 */

define(['N/runtime', 'N/log'], (runtime, log) => {
    function beforeLoad(scriptContext) {
        try {
            const recCurrent = scriptContext.newRecord;
            const objForm = scriptContext.form;
            const stStatus = recCurrent.getValue({
                fieldId: 'status'
            });
            const stSuiteletLinkParam = runtime.getCurrentScript().getParameter({
                name: 'custscript_suiteletlink'
            });
            const suiteletURL = '\"' + stSuiteletLinkParam + '\"';
            if (stStatus === 'Pending Fulfillment') {
                objForm.addButton({
                    id: 'custpage_suiteletbutton',
                    label: 'Open Suitelet',
                    functionName : 'window.open(' + suiteletURL + ')',
                });
            }
        } catch(error) {
            log.error({
                title: 'beforeLoad_addButton',
                details: error.message
            });
        }
    }
    return {
        beforeLoad: beforeLoad
    };
}); 

            

Build the Script

You can write the script using a step-by-step approach that includes the following:

• Start with required opening lines

• Create the entry point function

• Add the custom button to the sales order

• Create the return statement

• Save your script file

Note:

The code snippets included below do not account for indentation. Refer to The Complete Script for suggested indentation.

Start with required opening lines

JSDoc comments and a define function are required at the top of the script file. The JSDoc comments in this script indicate that it is a SuiteScript 2.1 user event script. The script uses two SuiteScript modules specified in the define statement:

• N/runtime - provides access to runtime parameters

• N/log – allows you to log execution details

Start a new script file using any text editor and place the following JSDoc comments and define function at the top of the file:

Note:

This tutorial script uses the define function, which is required for an entry point script (a script you attach to a script record and deploy). You must use the require function if you want to copy the script into the SuiteScript Debugger and test it. For more information, see SuiteScript Debugger.

                /**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 * @NModuleScope SameAccount
 */

define(['N/runtime', 'N/log'], (runtime, log) => {
}); 

              

Create the entry point function

This script is triggered on the beforeLoad entry point when a sales order that is in Pending Fulfillment state is loaded. A try-catch block is used to log any errors that might occur during script execution. Most of the script code will be placed in the try block.

Add the following function definition and initial try-catch block statements at the top of the define function:

                function beforeLoad(scriptContext) {
    try {
    } catch(error) {
        log.error({
            title: 'beforeLoad_addButton',
            details: error.message
        });
    }
} 

              

Add the custom button to the sales order

You want this script to add the custom button only if the sales order is in the Pending Fulfillment state.

Add the following code inside the try block:

                const recCurrent = scriptContext.newRecord;
const objForm = scriptContext.form;
const stStatus = recCurrent.getValue({
    fieldId: 'status'
});
const stSuiteletLinkParam = runtime.getCurrentScript().getParameter({
    name: 'custscript_suiteletlink'
});
const suiteletURL = '\"' + stSuiteletLinkParam + '\"';
if (stStatus === 'Pending Fulfillment') {
    objForm.addButton({
        id: 'custpage_suiteletbutton',
        label: 'Open Suitelet',
        functionName : 'window.open(' + suiteletURL + ')'
    });
} 

              

Create the return statement

This script associates the beforeLoad function with the beforeLoad user event entry point.

Add the following code immediately above the closing }); in your script:

                return {
    beforeLoad: beforeLoad
}; 

              

Save your script file

You need to save your script file so you can load it to the NetSuite File Cabinet. Before you save your script file, you may want to adjust the indentation so that the script is readable. Refer to The Complete Script for suggested indentation.

When you are happy with how your script file reads, save it as a .js file (for example, sl_executeSuiteletButton.js).

Step 2: Create the Script Record

Now that you’ve completed the script, you can upload the script file to the File Cabinet and create a script record for it.

For more information about creating script records, see Creating a Script Record.

To create the script record:

1. Upload your script to the NetSuite File Cabinet.

2. Go to Customization > Scripting > Scripts > New.

3. Select your script from the Script File list and click Create Script Record. The Script page is displayed.

4. On the Script page, enter the following values:

   Field	Value
   Name	Add Button to Execute Suitelet
   ID	_ue_custom_suitelet_button NetSuite prepends ‘customscript’ to this ID.
   Description	This script adds a button to the sales order form. When clicked, the button opens the Suitelet URL provided on the Parameters tab. (You may opt to include the button name you choose in the description to help others identify that this scripts controls that specific button.)

5. Optionally set any other fields on the script record as desired.

6. Click Save and Deploy. The Script Deployment page appears. Continue with Step 3: Deploy the Script.

Step 3: Deploy the Script

After you create the script record for your script, you can create a script deployment record for it. A script deployment record determines how, when, and for whom the script runs.

For more information about script deployment records, see Script Deployment.

To deploy the script:

1. Complete the steps in Step 2: Create the Script Record.

2. On the Script Deployment page, enter the following values:

   Field	Value
   Applies To	Sales Order
   ID	_ue_custom_suitelet_button NetSuite prepends 'customdeploy' to this ID.
   Status	Testing The Testing status allows the script owner to test the script without affecting other users in the account.
   Log Level	Debug The Debug level will write all log.debug statements in a script to the Execution Log tab of the script deployment record as well as all errors.
   Execute As Role	Current Role It is normally best practice to have scripts execute with the user’s current role to avoid granting unwanted access.
   Audience > Roles	Check Select All

3. Click Save.

Step 4: Create and Set the Script Parameter

This script uses a script parameter to specify the Suitelet link. When the custom button is clicked, a window is opened displaying the Suitelet. The script parameter for this script can be added after the script is deployed on the sales order record.

For more information about creating and setting script parameters, see Creating Script Parameters (Custom Fields).

To create the script parameter:

1. Go to Customization > Scripting > Scripts.

2. Locate your script in the list of scripts and click Edit next to the script name.

3. On the Script page, click the Parameters tab and click New Parameter. The Script Field page appears.

4. On the Script Field page, enter the following values:

   Label	ID	Type	Description	Preference
   Suitelet Link	_suiteletlink NetSuite prepends ‘custscript’ to this ID. The value ‘custscript_suiteletlink’ is used in the script.	Hyperlink	This is the location of the Suitelet.	Leave blank.

5. Click Save to save the script parameter. The Script page appears.

6. Click Save to save the script record with the updated script parameter.

After you have created the parameter, you must set the value of the parameter on the script deployment record that you created Step 3.

To set the script parameter:

1. Go to Customization > Scripts > Script Deployments.

2. Locate your script deployment in the list of script deployments and click Edit next to the script deployment name.

3. On the Parameters tab, enter your script parameter value for the URL from the Suitelet deployment that you want to display when the button is clicked.

4. Click Save.

Step 5: Test the Solution

After you create the script record and deploy your script, you can test your solution by editing a sales order that is in Pending Fulfillment status.

To test your solution:

1. Go to Transactions > Sales > Enter Sales Orders > List.

2. Click View next to a sales order that is in Pending Fulfillment status.

3. Verify your custom button, labeled ‘Open Suitelet’ appears on the sales order form. For example:

   

4. Click the button and verify your Suitelet opens in a new window.

Related Topics

• SuiteCloud Customization Tutorials
• Calculate Commission on Sales Orders
• Copy a Value to the Item Column
• Disable Tax Fields
• Hide a Column in a Sublist
• Populate Item Substitution
• Set a Default Posting Period in a Custom Field
• Set Purchase Order Exchange Rate
• Set the Item Amount to Zero for Marketing Orders
• Set Default Values in a Sublist
• Track Customer Deposit Balances
• Validate Order on Entry

General Notices