SuiteScript 2.x Hello World
To help you understand how SuiteScript 2.x works, this topic walks you through how to set up a basic customization. After you finish the steps in this topic, you'll see a “Hello, World!” message whenever you load a NetSuite task record.
This topic contains the following sections:
Key Concepts
Before you get started, it might help to review a few key concepts and terms that are central to SuiteScript 2.x development. Some of these terms appear in the steps later in this topic. You can read about these concepts now or skip ahead to Step 1: Enable the Feature.
SuiteScript Versions
The sample script here uses SuiteScript 2.0. There's also a newer version, SuiteScript 2.1, which supports new language features from ES2019. You can write your scripts in either SuiteScript 2.0 or 2.1.
-
For help writing scripts in SuiteScript 2.x, see SuiteScript 2.x Entry Point Script Creation and Deployment.
-
For more info about SuiteScript versions and 2.1, see SuiteScript Versioning Guidelines and SuiteScript 2.1.
SuiteScript Reserved Words
Like most programming languages, SuiteScript has a list of reserved words you can't use as variable or function names in your scripts. For example, var is used to declare a variable, and try marks the start of a try-catch block. For more information, see SuiteScript Reserved Words.
SuiteScript 2.x Script Types and Entry Points
Before you start writing your script, you need to pick which predefined script type to use. Each script type is made for certain situations and specific triggering events. The following are some of the available SuiteScript 2.x Script Types:
-
The SuiteScript 2.x Client Script Type is for scripts that should run in the browser.
-
The SuiteScript 2.x Scheduled Script Type is for server scripts that should run at a specific time or on a recurring schedule.
-
The SuiteScript 2.x RESTlet Script Type is for server scripts that should execute when called over HTTP by an application external to NetSuite.
Each script type has one or more entry points unique to that type. An entry point is where the system hands control of NetSuite to your script. When you add an entry point to your script, you're telling the system to do something when that entry point is triggered. This runs a function in your script, called an entry point function.
For many script types, entry points are like events, or the different things that can happen, to trigger your script. For example, client script entry points are events that can happen in a browser session, like fieldChanged(scriptContext) when a field value changes, or pageInit(scriptContext) when a page loads. In contrast, the scheduled script type has only one entry point, called execute. This is when a schedule runs the script or a user runs it manually.
In the example in this topic, you want a dialog alert to pop up when someone loads the NetSuite task record page in a browser. So, this example uses the client script type and the pageInit entry point.
SuiteScript 2.x Modules
SuiteScript 2.x uses Modular Architecture. All its APIs are organized into standard modules, and each module’s name shows what it does. For example, the N/record Module lets you work with NetSuite records, while N/https Module lets you make HTTPS requests to external web services.
Most modules need to be loaded in your script before you can use their APIs. Loading a JavaScript module is kind of like importing a library in Java—it gives you access to code that's defined somewhere else. In an entry point script, you load modules through the define Object. You list the modules you want to load as arguments.
Some APIs are globally available, so you can use them without loading their modules first. You’ll find a list of these globally available APIs in SuiteScript 2.x Global Objects.
The example in this topic uses both: some globally available APIs, and a method that only works after you load the right module.
Entry Point Scripts Versus Custom Module Scripts
The example script here is pretty simple—everything’s in one file. But sometimes you’ll want scripts that use logic from other files. In SuiteScript 2.x, these extra files are called custom module scripts.
The main script file—the one that sets the script type, entry point, and entry point function—is called an entry point script. Entry point scripts have their own formatting rules, which are different from custom module scripts. The next steps in this topic point out some of these requirements.
This topic doesn’t cover custom module scripts. For more on those, see SuiteScript 2.x Custom Modules.
Step 1: Enable the Feature
Before you can do the rest of the steps in this topic, you’ll need to make sure the Client SuiteScript feature is enabled in your NetSuite account.
If you’re not sure whether the feature’s enabled, check by going to Customization > Scripting > Scripts. If you can follow that path, the feature is enabled. If you don’t see the option, it might be because you don’t have permission or the menu path was customized. If you’re still not sure, ask your account administrator.
An account administrator or anyone with the Enable Features permission can turn on the feature. To enable it, follow these steps.
To enable the Client SuiteScript feature:
-
Select Setup > Company > Enable Features.
-
Click the SuiteCloud subtab.
-
Find the Client SuiteScript option. If the box is already checked, skip to Step 2: Create the Script File. If it isn’t, go ahead and check it.
You’ll see a window with the terms of service.
-
If you agree to the terms, scroll to the bottom and click I Agree.
-
You don’t need Server SuiteScript for these steps, but if you plan to do more SuiteScript development later, you might want to check the Server SuiteScript box. If you check the box, you’ll see another window with the terms of service. Click I Agree.
-
Click Save.
Step 2: Create the Script File
First, you’ll need to create a script file called helloWorld.js. You can either copy the full script from Copy the Full Script, or follow the steps below to make your own helloWorld.js script.
All entry point scripts need to include the required components described in SuiteScript 2.x Anatomy of a Script.
Create the Script Step by Step
To create the script file:
-
Open a new file in your favorite text editor.
-
Add two JSDoc tags:
-
@NApiVersion– This is the version of SuiteScript you're using. -
@NScriptType– This is the script type you're using.
After each JSDoc tag, add the right value, like you see in the following snippet.
/** *@NApiVersion 2.0 *@NScriptType ClientScript */ ...Every SuiteScript 2.x entry point script needs to have these tags, and you can only use one value for each. For more details and a list of valid values, check out SuiteScript 2.x JSDoc Tags.
-
-
Add the define Object—every entry point script needs to use it.
Use [‘N/ui/dialog’] as the define function’s first argument for the define function. This argument is an array of string values for the modules you want to load.
... define(['N/ui/dialog'], // In Step 4, you will add additional code here. );The N/ui/dialog Module has methods for showing different types of dialogs. You load it so your script can use one of those methods.
-
Declare a callback function as the second argument for the define function, and give it one argument called dialog.
... function(dialog) { // In Step 5, you will add additional code here. } ...If you’re not familiar with callback functions, know that this function will hold all the other logic for your script. Also, the number of arguments in your callback function has to match the number of modules you load with the define function. Each argument is an object that lets you access its module, so it’s a good idea to name each argument after its module.
In this example, the define function loads one module, so the callback function only needs one argument.
-
Inside the callback function, declare a function named helloWorld.
... function helloWorld() { // In steps 6-10, you will add additional code here. } ...Later, you’ll set the helloWorld function as the script’s entry point function. Every entry point script needs to have one.
A function only counts as an entry point function if it’s linked to an entry point. You’ll make that link in Step 11.
-
Inside the entry point function, create an object called options.
Many SuiteScript 2.x methods need or can take a plain JavaScript object as their argument. The method you use to create the “Hello, World!” dialog is one of them. This method takes an object with two parameters: title and message.
... var options = { title: 'Hello!', message: 'Hello, World!' }; ... -
Add a try/catch statement. You don’t have to, but it helps your script handle errors gracefully. If an error happens and your try/catch handles it, your script—and any others on the page—can keep running. Try/catch can also help you figure out why something went wrong. Keep in mind, try/catch is a JavaScript feature, not something specific to SuiteScript 2.x.
A basic try/catch has two parts: the try block holds the code you want to run, and the catch block runs if there’s a JavaScript error in the try block.
Add the try/catch statement after the object you created in Step 6.
... try { // In steps 8 and 9, you will add additional code here. } catch (e) { // In Step 10, you will add additional code here. } ... -
For the first action in the try block, call the N/ui/dialog Module alert() method. This method pops up a dialog with a title, a message, and an OK button.
You call this method using the dialog object you set up in Step 4, along with the method name alert. To set the dialog’s title and message, pass in the options object.
... dialog.alert(options); ...For more details about this method, check out the dialog.alert(options) reference page. The page title matches the code you’ve added to your script, but keep in mind that reference pages for standard module methods might not always match your naming conventions. For example, if you named your callback argument message, you’d call the alert method with message.alert(options).
Also, in the documentation, each method’s argument is usually called
options, but in your script, you can name the object whatever you want. You can even create the object right when you call the method. -
Add some logic to create a log entry when the dialog shows up successfully. You can do this with the globally available log.debug(options) method.
The debug() method is called on the log object. Unlike the dialog object, which you had to load, the log object is always available in every script. That’s why you don’t give it a name—you can always write log.debug to use this method.
This method takes an object with two properties: a title and a detailed message. This time, create the object right in the method call. That’s different from what you did in Step 4, where you made the object first and then passed it by name to alert().
... log.debug ({ title: 'Success', details: 'Alert displayed successfully' }); ...The log entry shows up in the UI when someone triggers the dialog alert. You’ll find out how to view the log in Step 5: Test the Script.
-
In the catch block, add some logic to create a log entry if there’s an error. You can use the globally available log.error(options) method for this. The log.error() method works a lot like log.debug(), but the log entry is marked as an error instead of a debug message.
... log.error ({ title: e.name, details: e.message }); ... -
Right after the entry point function, add a return statement. In every SuiteScript 2.x entry point script, your return statement needs at least one line with two parts:
-
An entry point, which is pageInit(scriptContext) here.
-
A function, which is helloWorld here.
... return { pageInit: helloWorld }; ...Because of this reference, helloWorld counts as an entry point function.
Even though this script uses just one entry point, your return statement can include more if you want. You can use multiple entry points as long as they all match the script type set by the
@NScriptTypetag at the top of your file. For example, besides pageInit(scriptContext), the client script type also has saveRecord(scriptContext). So if you want the script to do one thing when the page loads and something else when the user clicks Save, you can use both entry points. For an example of a script with multiple entry points, check SuiteScript Client Script Sample. -
-
Save the file and name it helloWorld.js.
Copy the Full Script
This section shows the full sample script. If you haven’t already created the script file by following the steps in Create the Script Step by Step, copy and paste the following code into a text file. Save the file and name it helloWorld.js.
/**
*@NApiVersion 2.0
*@NScriptType ClientScript
*/
define(['N/ui/dialog'],
function(dialog) {
function helloWorld() {
var options = {
title: 'Hello!',
message: 'Hello, World!'
};
try {
dialog.alert(options);
log.debug ({
title: 'Success',
details: 'Alert displayed successfully'
});
} catch (e) {
log.error ({
title: e.name,
details: e.message
});
}
}
return {
pageInit: helloWorld
};
});
Step 3: Upload the Script File to NetSuite
After you’ve created your entry point script file, upload it to your NetSuite File Cabinet.
To upload the script file:
-
In the NetSuite UI, go to Documents > File > SuiteScripts.
-
In the left pane, select the SuiteScripts folder and click Add File.
-
Follow the prompts to find the helloWorld.js file on your computer and upload it.
Keep in mind that even after you upload the file, you can edit it right in the File Cabinet if you need to. For details, see Editing Files in the File Cabinet.
Step 4: Create a Script Record and Script Deployment Record
In general, before an entry point script can run in your account, you’ll need to create a script record for the script file. You’ll also need to create a script deployment record.
The script deployment record holds part of the logic for when the script runs. Some of that logic is in the script itself, based on the entry point you use. For example, if you use the pageInit(scriptContext) entry point, you’re telling the system to run the script when a page loads. But you also need to say which specific page should trigger the script. In other words, you have to tell the system which record type this script should run on, and you do that with the script deployment record.
You can create these records programmatically, or you can set them up in the UI, as shown in the following steps.
To create the script record and script deployment record:
-
Go to Customization > Scripting > Scripts > New.
-
In the Script File dropdown, select helloWorld.js.
If you haven’t uploaded the file yet (see Step 3), you can do it right from this page. Move your cursor to the right of the dropdown to see a plus icon. Click it to open a window where you can upload your file.
-
After you’ve selected the file, click the Create Script Record button.
The system will show a new script record, with helloWorld.js listed on the Scripts subtab.
-
Fill out the required fields like this:
-
In the Name field, enter Hello World Client Script.
-
In the ID field, enter _cs_helloworld.
-
-
Click the Deployments subtab to create the deployment record.
-
Add a line to the sublist like this:
-
Set the Applies to dropdown to Task. If you want the dialog to show up for a different record type, select that from the list instead.
-
In the ID field, enter _cs_helloworld.
Leave the other fields as they are. The Status field is set to Testing, which means the script won’t deploy for other users. If you want to make this customization available to everyone later, edit the deployment and set the status to Released.
-
-
Click Save.
The system creates the script and script deployment records.
Step 5: Test the Script
Now that the script is deployed, you should make sure it runs as expected.
To test the script, follow these steps:
-
Check that the dialog alert pops up when it should:
-
Open a task record by going to Activities > Scheduling > Tasks > New.
If the script is working properly, the system will show a dialog alert.
-
Confirm and close the dialog by clicking OK.
-
-
Check that the expected log entry has been saved to the script deployment record:
-
Go to Customization > Scripting > Script Deployments.
-
Find your deployment and click View.
-
Click the Execution Log subtab.
The subtab should show an entry like the following.
You’ll also see the same entry on the Execution Log of the script record.
If there was an error, the error log entry you created would show up instead of the debug entry.
-
Next Steps
Now that you’ve deployed your first script, you might want to check out other topics in the SuiteScript 2.x API Introduction. Or, if you want to experiment with other script samples, try these:
-
Another commonly used script type is the user event type. This one’s for server scripts that run when users do certain things with records. To try a simple user event script, see SuiteScript 2.x User Event Script Tutorial.
-
For a slightly more complex user event script, check out SuiteScript 2.x User Event Script Sample.
-
For an example of a custom module script and a user event script that calls a custom module function, see SuiteScript 2.x Custom Module Tutorial.