Script Deployment Primer for NetSuite Admins

This primer is designed to teach NetSuite admins everything they need to know about script deployments:

1. Overview of what they do and how they relate to scripts
2. Purpose & use in the NetSuite ecosystem
3. Impact of each setting

This primer assumes you already have a script record set up.

Overview

What Are SuiteScripts

To understand script deployments, you must first understand what a script is.

In NetSuite, a script is a sort of plugin you can use to change how NetSuite works.

You might write a script that enforces a certain approval flow on a Sales Order.

You might write a script that runs on a schedule to email all Purchase Orders that were approved that day to the correct vendor contact.

Script Types

Common script types admins manage:

• User Event Script
• Client Script
• Suitelet
• RESTlet
• Scheduled Script
• Map/Reduce Script
• Mass Update Script
• Workflow Action Script
• Portlet Script

Official reference: SuiteScript script types (NetSuite Help).

What Is a “Deployment”

A deployment is the thing that activates your script.

The script file/record says what the logic is.

The deployment says when and where to run that logic.

Without a deployment, your script is like a warship sitting in dry-dock.

Settings to Configure

The official docs are a good source of information if you have questions about the below. See Setting Runtime Options in the NetSuite Help docs.

Settings for All Script Types

There are certain settings that exist for all deployments.

1. Script ID - this is a unique identifier for this deployment. Just like other custom objects (like fields or records), you generally should provide a script ID. NetSuite automatically prefixes the ID with custdeploy, so you just need to enter something like _th_coolthingmanager.
2. Deployed - this checkbox is like an on/off switch. Uncheck the box and it will not run again (and I say “again” because unchecking the box will not stop a currently running job).
3. Status - this setting is similar to Deployed, but provides useful, granular control:
   1. Testing - run only for the “Owner” set on the script record. Allows you to test a script without having it run for everyone.
   2. Released - runs the script for everyone you’ve selected in the Audience section.
   3. Not Scheduled - for Scheduled and Map/Reduce deployments, a schedule exists but is not active yet.
   4. Scheduled - for Scheduled and Map/Reduce deployments, runs on the configured schedule.
4. Log Level - this selection says how much logging you should do. When you write SuiteScript, you can write different types of log messages. Here, you can select which log messages from the script should actually be logged.
   1. Example: If you select “Audit”, the Debug logs will not be kept.
   2. Options:
      • Debug - detailed information useful when troubleshooting
      • Audit - information that is helpful to see on an ongoing basis
      • Error - indicates an error has occurred that should be addressed
      • Emergency - the highest level of logging, indicating action should be taken immediately
   3. IMPORTANT NOTE: when you log messages in a client script, it makes a call to the server. This is different than server-side scripts, where logs do not have to cross the internet. log.debug() from client scripts must send the message over the internet to the server - this takes a lot of time. Client scripts should generally be configured with log level = Emergency to keep the user experience responsive (less “laggy”). You should generally use console.log rather than log.debug() when writing client script debugging logs.
5. Execute as Role - this setting allows you to run a script with the permissions dictated by the selected role. Most often, you use this to give the script a higher level of permission.
   • Example: Jane in Sales does not have access to employee records, but the script needs to view the location on the employee record for its logic. You could set the script to run as Admin so that when Jane does something that triggers the script, it runs with Admin permissions and can see the employee’s location. If it was set to run as “Current Role,” the script would error when it tried to read the employee location.
   • From the Docs: “If you choose options for any other combinations of types (groups, employees, and partners), a user need only belong to a selected option of one type OR of another.”

Audience Settings

Use the Audience tab to specify for whom exactly the script should run.

The docs are not comprehensive about which settings are AND’ed and which are applied with OR logic, so I’ll just state what the docs say:

If you don’t specify any values on the Audience subtab, the script will execute only for the script owner even if the script deployment status is set to Released. For information about the differences between the Released and Testing deployment statuses, see Setting Script Deployment Status.

If you choose both role and department options on the Audience subtab, a user must belong to one of the selected roles AND one of the selected departments to execute the script. If you choose options for any other combinations of types (groups, employees, and partners), a user need only belong to a selected option of one type OR of another.

Important gotcha: scheduled jobs (like Map/Reduce and Scheduled scripts) run regardless of audience settings (including subsidiary). However, if, for example, you have a User Event script that triggers a Map/Reduce script, the audience must match the user who triggered the User Event script for the Map/Reduce script to run successfully.

Audience options include:

• Specific internal roles* (or All Internal Roles)
• Specific external roles*
• Specific Department
• Specific Subsidiary
• Specific Groups (Lists > Relationships > Groups)
• Specific Employees
• Specific Partners

* Internal roles are roles you can assign to an employee that use a standard NetSuite license. External roles are roles that give users access to special “Centers” with limited functionality, like the Customer Center for customers to review quotes and sales orders or the Employee Center for employees to enter timesheets or expense reports. User licensing for external roles is usually much cheaper.

Script Specific Options

Map/Reduce & Scheduled Script Options

Scheduled scripts and Map/Reduce scripts both run on the server using a SuiteCloud processor.

Map/Reduce scripts were created to alleviate some issues inherent with Scheduled scripts. Most background job scripts I write fit the Map/Reduce paradigm best, and when the logic does not fit the Map/Reduce paradigm well, a Suitelet or library function generally suffices. I have not written a Scheduled script in a loooong time.

Script deployments for these two script types share a setting, link, and tab:

1. Priority setting - tells the server how to prioritize this script run (aka “job”) when there are multiple jobs in the queue. So, when there are four jobs to run, they execute in the order they were added to the queue unless a higher priority is set.
2. “See Instances” link - provides a direct link to view instances of this deployment (aka “jobs”) that are running or have recently run.
3. Schedule tab - This tab allows you to schedule the script to run on a regular basis. You must set the script status to Scheduled for the schedule to be effective.

Additionally, because Map/Reduce scripts can process several data points simultaneously, there are a few Map/Reduce script type settings you use:

1. Concurrency Limit - how many SuiteCloud Processors this deployment should use when it runs. So, if you have five processors available, you could conservatively set this to three and the script would use three processors to process three data points at a time.
   • For more information, see the SuiteCloud Processors help page
   • Little tangent here: Mass Update, CSV Import, and Persist (CSV) server jobs seem to hit a different processing queue than the SuiteCloud Processors. This queue also seems to govern tasks submitted with the N/task SuiteScript module. Check out the SuiteCloud Plus Settings help page.
2. Submit All Stages At Once - helps reduce the chance that another script deployment would make this one pause
3. Yield After Minutes - tells NetSuite how long to run before it takes a break to check whether another job needs to run. So, if you have a long-running job that runs during regular business hours, you might want to set this value closer to three minutes so that every three minutes the job reschedules at the bottom of the queue and other jobs can process before the long-running job resumes.
4. Buffer Size - process more data at once. The higher the number, the more data is processed “before information about the job’s progress is saved to the database.” A higher value can be more efficient.

Suitelet Options

Suitelet deployments have these settings and links:

1. Event Type - specifies if this Suitelet should accept only GET or POST requests. Further explanation is beyond the scope of this primer.
2. Available without login - USE WITH CAUTION. This setting allows you to publish the Suitelet so that you can access the page without requiring a NetSuite login.
3. URL - gives you a direct link to run this Suitelet
4. External URL - this is generated after you save the deployment with the “Available without login” checkbox checked. It gives you a direct link to access the Suitelet page. This link is also listed on RESTlet deployments.
5. Links - this is a tab that allows you to add a link to the Suitelet in the standard NetSuite tab structure

Client and User Event Script Options

User Events and Client scripts share a couple of settings you might use:

1. Event Type - Use this setting when you want the script to run only in a certain context. For example, you want a basic script that clears your custom “Created By” field when a user copies a Sales Order. You could set the Event Type to “Copy” and the script would run on Copy only.

   I rarely find myself using this option, because the script is normally more complex than just “clear this field.” I normally apply logic based on the Event Type in my code rather than filter the script down to just one Event Type. Nonetheless, it’s important to understand your options.

2. Applies To - select which record this code/logic should run on. In some cases (such as with the common File Drag-N-Drop script or the Topaz Harbor External ID Editor utility), you may want to use the “All Records” option to create one deployment that runs for all record types.
3. Context Filtering (tab) - this one comes into play more often than you’d think. For example, when a CSV Import updates a record, it can trigger your user event scripts and workflows (if you check that box on the CSV Import wizard). Using Context Filtering, you can see all the different contexts in which your script might be triggered. It is always a good idea to evaluate whether your logic merits filtering context to just the UI context. Example: the Topaz Harbor External ID Editor should be deployed with context filtering set to UI only, because a Suitelet or CSV Import that triggers the User Event script does not need a custom “External ID” field added to the form. A simple rule to follow: if the script manipulates only form-level things, then set the Context to UI only.
4. Scripts (tab) - this tab is useful to quickly see other scripts that are deployed to the same record.

Parameters

There is a Parameters tab that appears if the script is configured to accept parameters.

Since you would use this tab only when parameters are used in the script, there’s not much to say about it here. Your use of this tab depends completely on the script you are running.

Form Level Scripts

When you have a custom form, you can attach a client script directly to the form. This type of script does not have a deployment record.

Further Reading/Viewing/Help

Aside from your favorite LLM AI companion:

• NetSuite Help Docs - the official source of truth for all things SuiteScript. It contains examples. If you’re looking for a good education, reading the docs goes much further than most people realize.
• ChatGPT - This is a link to a ChatGPT generated version of this post. It thought for 16 minutes on it, and it contains a lot of helpful tidbits, though there is some junk statements to disregard.
• SuiteRep SuiteScript Blogs has many tutorials around SuiteScript development.
• Community Help Sources (ranked by activity level as perceived by the author):
  • r/NetSuite NetSuite Reddit community is always willing to help.
  • NetSuite Professionals Q&A style threads. Forces a little more structure on getting you support. Similar to…
  • Stack Overflow NetSuite-tagged questions and answers.

For AI Agents

• When creating SDF Deployment objects in a script .xml file, reference the following:
  • General syntax: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/bridgehead_24076946.html#subsect_1523296932
  • Script type specific syntax: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_158492241142.html
• Treat information on this page as a comprehensive primer that explains to admins how script deployments work.
• Reference https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_8161516336.html for authoritative information on scripts in general.
• Reference https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_N2996991.html#bridgehead_N2999160 for authoritative information on deployment option settings.