Suitescript 2017.1 Release Notes

Suitescript 2017.1 Release Notes

Published 07/25/2013 11:39 PM   |    Updated 05/04/2017 11:49 PM   |    Answer Id: 31709

Refer to the following sections for details on all SuiteScript updates for NetSuite 2017.1:

Enhanced Security for Admin Scripting

With the 2017.1 release, NetSuite is adding new SuiteScript restrictions to the Administrator and Full Access roles. These enhancements contribute to improved security and impact both SuiteScript 1.0 and SuiteScript 2.0 scripts. Note that these restrictions apply to all NetSuite environments (see Understanding NetSuite Environments). As of 2017.1, you are no longer able to perform the following actions with SuiteScript:

  • Create an entity record where any role is set to Administrator or Full Access
  • Delete an entity record where any role is set to Administrator or Full Access
  • Edit an entity record so that the entity gains an Administrator or Full Access role
  • Edit an entity record so that the entity loses an Administrator or Full Access role
  • Edit the password or email field value on an entity record where any role is set to Administrator or Full Access

Scripts that violate these new restrictions throw the following error message: Script Security Violation: Unauthorized attempt to <operation> entity with <role> role by SuiteScript! If you have not already done so, audit your existing scripts for the use cases listed above. Update all applicable scripts to conform to the new restrictions.

New SuiteScript Scheduling Permission

This release introduces the SuiteScript Scheduling permission. In previous releases, you needed the Administrator role to execute scheduled scripts and map/reduce scripts with an API. You also needed the Administrator role to use scheduling specific APIs (see tables below). With 2017.1, you can now use a role with the SuiteScript Scheduling permission as an alternative to using the Administrator role. This gives you additional granularity when performing audits.


This feature does not impact scheduled scripts or map/reduce scripts executed in the UI. The permission requirements for this action are included in the tables below and are unchanged.

The following tables demonstrate how the new SuiteScript Scheduling permission can be used.

Previous Releases
Action Role/Permission Required
Use one of the following APIs:

Administrator role
Execute a scheduled script or a map/reduce script with an API (for example, ScheduledScriptTask.submit()). Administrator role
Execute a scheduled script or a map/reduce script in the UI. Open the applicable deployment record and click Save and Execute. Administrator role or role with SuiteScript permission (Full level)
Action Role/Permission Required
Use one of the following APIs:

Administrator role or role with SuiteScript Scheduling permission
Execute scheduled script or map/reduce script with an API (for example, ScheduledScriptTask.submit()). Administrator role or role with SuiteScript Scheduling permission
Execute scheduled script or map/reduce script in the UI. Open the applicable deployment record and click Save and Execute. Administrator role or role with SuiteScript permission (Full level)

Web Store Performance Enhancement – User Event Script Execution Context

For NetSuite accounts that use SuiteCommerce, NetSuite 2017.1 includes a new option that can help improve web store performance. This option is available for all user event script deployments. It controls whether a script executes when the triggering event takes place in the web store. The Execute in Commerce Context option appears as a check box on script deployment records. When this box is cleared, the script does not execute in response to a triggering event that occurs in SuiteCommerce Advanced, SuiteCommerce Site Builder, or SuiteCommerce InStore. When your account is upgraded to 2017.1, this box is added and automatically checked on all existing user event script deployment records. However, if appropriate, you can edit any script deployment record and clear the box. In contrast, when you create a new script deployment record in 2017.1, the box is cleared by default. Scripts can significantly slow web store performance. By leaving this option cleared, you can improve web store response times. However, in some cases, you may want a script to execute in response to web store activity. To enable the option, you must check the Execute in Commerce Context box. For details about working with script deployment records, see Script Deployment. Previous releases of NetSuite also included features that let you customize the impact of scripts on the web store. Other existing features include:

  • Asynchronous afterSubmit Sales Order Processing – When you enable this feature, all afterSubmit user events and workflows triggered by web store checkout run asynchronously. For details, see Enabling Ecommerce Features.
  • Scriptable Cart – This option lets you designate specific forms to be used for sales orders generated through shopping cart activity. You can customize these forms, and any scripts they use, for the web store. For details on this feature, see Scriptable Cart.

Changes to SuiteScript Handling of Header Names

In 2017.1, NetSuite has made changes to the way SuiteScript handles HTTP request headers. In the past, when NetSuite exposed HTTP request data to a script, it provided the HTTP headers in the same case that they were provided by the requesting client, usually a web browser. NetSuite required that scripts use an exact case-sensitive match for each header name. Now, the handling of these names has changed. The details vary depending on the version of SuiteScript and the method being used. These changes bring SuiteScript into alignment with the HTTP specification.

SuiteScript 2.0 and SuiteScript 1.0’s getAllHeaders() Method

For SuiteScript 2.0, and for SuiteScript 1.0’s getAllHeaders() method, header names are now exposed in lower-case form. The system also attempts to add a title case version of each header. For this reason, when you retrieve all headers for a request, typically you will now see two iterations of each header: one in lower-case and one in title case. You can interact with these title-case headers as you would with their lower-case counterparts. However, creation of title-case headers is not guaranteed, particularly for custom headers. Therefore, for best results, write header names in lower-case letters. In particular, avoid using all-caps or unusual capitalization styles. For example, suppose your script interacts with a custom header called HOSTTYPE. In past releases, your script might have used the following expression:

In this release, you would change that expression to the following:

SuiteScript 1.0’s getHeader() Method

In SuiteScript 1.0, there is one exception to the preceding guidance. When you use the getHeader() method, the system reads the header name you provide in a case-insensitive manner. Capital letters do not cause problems. For example, both of the following expressions return the appropriate values:

For this reason, scripts that did not previously return data may return values after your account is upgraded to 2017.1.

Workflow Action Script Type Extended

In 2017.1, the workflow action script type has been extended for both SuiteScript 1.0 and SuiteScript 2.0. With this change, workflow action scripts can now reference two additional optional parameters:

  • type – An event type, such as create or edit.
  • form – The form through which the script interacts with the record. This parameter is available only in the beforeLoad context.

The following SuiteScript 1.0 snippet uses both new parameters. This snippet would add a button to the form if the record were opened in edit mode:

Similarly, in SuiteScript 2.0, the context object that is made available to workflow action scripts now includes the type and form parameters. Additionally, workflowId has also been added as a new parameter in SuiteScript 2.0. Previously, this parameter was available only in SuiteScript 1.0.

Enhancement for the Deposit Record

In 2016.2, SuiteScript’s handling of the deposit record was enhanced. When you use SuiteScript to create or load a record, you can now control whether the script will respect the filter preferences created by the user on the record’s Deposits > Payments subtab. Set the new disablepaymentfilters initialization parameter to false if you want the system to respect these preferences. Set the parameter to true to ignore the preferences. In SuiteScript 1.0, you use the initializeValues parameter, which is part of the nlapiCreateRecord(type, initializeValues) and nlapiLoadRecord(type, id, initializeValues) methods. For example, the following SuiteScript 1.0 snippet would ignore the user’s preferences.

In all cases, if you do not set a value for the disablepaymentfilters parameter, it defaults to false.

Prevention of Updates to Entity Field on Currency Adjustment Journal Entries

As of 2017.1, you cannot use SuiteScript to update the entity field of the Journal Entry record for a specific kind of system-generated journal entry. The type of journal entry affected is the currency adjustment journal. This journal entry is generated during revenue reclassification for multi-currency transactions when the Revenue Commitment feature is enabled. Scripts that attempt to change the entity will not fail, but the entity will not be changed, and no error will be returned.

SuiteScript 2.0 – Flat File Streaming Support

The 2017.1 release provides support for flat file streaming:

SuiteScript 2.0 file Module – New Flat File Streaming APIs Support Files over 10MB

In previous releases, you could not easily access the contents of a file over 10MB. Large files needed to be split into partitions to save successfully, and stitched back together for loading. With NetSuite 2017.1, you can use new file streaming APIs to more efficiently process and stream large CSV and plain text files. You can load and edit each line into memory using File.lines.iterator(). Call File.appendLine(options) to append the lines back together. Note that you cannot iterate on and append lines at the same time. The File.resetStream() method resets the reading and writing streams that may have been opened. To help you monitor the size of a file, the File.size property now holds a dynamic value. The value is a sum of the saved file size plus any updated or appended lines currently in memory. For an example demonstrating use of these new APIs, see the following code sample:

Although the File.getContents() method continues to support only files under 10MB, the file streaming APIs enforce the 10MB limit only on individual lines of content. You no longer need to partition your files into smaller, separate files to read, write, and append file contents in memory.


Note: File streaming APIs are designed for CSV and plain text files. They are not suitable for binary files or structured, hierarchal data (such as JSON or XML files).

Flat File Streaming API – Map/Reduce Integration

As part of file streaming enhancements, the map/reduce script type has been enhanced so that you can stream text or CSV file contents during the map stage. You can point to a file using a file path or file ID. The map/reduce framework can now pass one line per map function invocation. To pass in a file as input data, when you invoke getInputData(), do one of the following:

  • Load or create a file.File Object.
  • Use an mapReduce.ObjectRef Object. Set the type to ‘file’ and provide an absolute or virtual bundle path to a file.

SuiteScript 2.0 – Asynchronous Search API Beta Release


Asynchronous Search APIs are a beta feature. The contents of this feature are preliminary and may be changed or discontinued without prior notice. Any changes may impact the feature’s operation with the NetSuite application. NetSuite warranties and product service levels shall not apply to the feature or the impact of the feature on other portions of the NetSuite application. NetSuite may review and monitor the performance and use of the feature.

NetSuite 2017.1 exposes to SuiteScript 2.0 the ability to trigger asynchronous search operations, and to automatically export these results into a CSV file stored in the file cabinet. Before 2017.1, the ability to persist large search result sets was accessible only from the NetSuite UI. Now, you can execute SuiteAnalytics persisted search functionality using the N/task Module. The feature extends the existing N/task module with an additional task type Object. This new task type enables you to place an execution of an existing NetSuite search into the SuiteScript task queue. Persisting search results enables you to run saved searches asynchronously, for up to 3 hours. Two new Object types are supported:

  • task.SearchTask – encapsulates a task that initiates an asynchronous search
  • task.SearchTaskStatus – holds a value indicating task search progress, similar to existing task status objects.

Use the task.create(options) method to create a task.SearchTask Object. To specify the CSV file that holds results in the file cabinet, set the following new parameters: options.savedSearchID and options.fileId or options.filePath The task.TaskType enum now supports an additional value: SEARCH.


There a limit to the number of asynchronous searches running at the same time. The limit is set to be the same as the limit for CSV import. The file size limit is based on File Cabinet limits. The API itself does not introduce any additional restrictions.

SuiteScript 2.0 – New Method for Retrieving NetSuite Domain Data

In 2017.1, SuiteScript 2.0 includes a new method that lets you dynamically discover the correct domain name for any NetSuite account. This logic is important because the domain names for NetSuite accounts are dynamic and can change without warning. If you want to create absolute URLs to records and other resources within your NetSuite account, they must be dynamically generated using the correct domain name. It is also important to dynamically discover domains in scripts that will be bundled and distributed for use in multiple NetSuite accounts. The url.resolveDomain(options) method lets you retrieve the correct domain names for any NetSuite account. The url.resolveDomain(options) has one mandatory parameter, hostType, which identifies the type of domain you want to retrieve. You populate this parameter by using the url.HostType enumeration. An optional parameter, accountId, identifies the NetSuite account for which you want to retrieve data. If no account is specified, the system retrieves data for the account that is running the script. The following table shows sample results that you might get when using each of the available values for the url.HostType enum. Note that the url.resolveDomain(options) method returns only a domain name. It does not return a scheme (such as https://).

url.HostType Value Sample Result


The sample results in the preceding table show domain names for the NA Northwest data center. Results will vary depending on which data center hosts the account named by the accountId parameter. For a full list of all data center IDs, see Understanding NetSuite URLs and Data Centers. For details about other tools that let you discover domain names, see Understanding Multiple Data Centers.

The following example shows how to use the url.resolveDomain() method to retrieve the application domain for the account with ID 012345.

The next example shows how you can use the url.resolveDomain() method in conjunction with other logic to create an absolute URL. In this example, no value is given for the accountId parameter. For that reason, the script retrieves the domain for the account where the script executes.

A related enhancement is the addition of the account ID parameter to the relative URLs returned by some N/url Module methods. For details, see SuiteScript 2.0 – Account ID Parameter Added to Relative URLs.

SuiteScript 2.0 – Account ID Parameter Added to Relative URLs

The SuiteScript 2.0 N/url Module includes several methods that return relative URLs. In 2017.1, these methods have been enhanced to include the appropriate NetSuite account ID. This value is identified by the compid parameter. For example, in 2017.1, the url.resolveRecord(options) method returns a string like the following:

The same method in 2016.2 returned a string like the following:

In addition to url.resolveRecord(options), this change affects the url.resolveScript(options) and the url.resolveTaskLink(options) methods. Note that, even in 2016.2, the url.resolveScript(options) results already included the compid parameter when you used the method to retrieve an external URL (when the method’s returnExternalUrl parameter was set to true). Now, the system also includes the compid parameter when the method’s returnExternalUrl parameter is set to false. This enhancement may benefit you if you use any of these methods to create absolute URLs. For example, you may need to create absolute URLs for distribution to people who may not be logged in to NetSuite. The addition of the compId parameter ensures that such links lead to the correct resources. Prior to this enhancement, if the intended user had access to more than one NetSuite account, it was possible for a request to be routed incorrectly. This enhancement complements the new resolveDomain method, which is described in SuiteScript 2.0 – New Method for Retrieving NetSuite Domain Data. If you have created extremely specific methods of parsing URLs that do not account for the new parameter, you should review your integrations and make the appropriate changes. Otherwise, this change should not affect your integrations.

SuiteScript 2.0 – New Methods for Working With Select Options

In 2016.2, SuiteScript 2.0 introduced new methods to work with select and multiselect fields that were created by a front-end Suitelet or beforeLoad user event script. These methods are similar to the following SuiteScript 1.0 APIs:

The new methods, Field.insertSelectOption(options) and Field.removeSelectOption(options), are part of the N/currentRecord Module. Because these methods operate at the field level, they can be used with either body fields or sublist fields. As with the 1.0 APIs, the new methods work only in client scripts, and only on fields whose IDs begin with the prefix custpage.

2017.1 SuiteScript Record Exposures

Record Type Newly Exposed/Update Notes
Advanced Intercompany Journal Entry Newly Exposed An advanced intercompany journal entry includes all of the operations of the original journal entries, in addition to new time-saving functions. For more information about this newly introduced record, see Advanced Intercompany Journal Entries.
Fulfillment Request Newly Exposed Available when the Fulfillment Request feature is enabled. For more information about this record, see Fulfillment Requests.
Project Revenue Rule Newly Exposed Available when the when the Project Management, Charge-Based Billing, and Advanced Revenue Management features are enabled. All three types of project revenue rules are supported: labor based, fixed amount, and percent complete.
Revenue Recognition Event Newly Exposed Available when the Advanced Revenue Management feature is enabled.
Shopping Cart Newly Exposed This record is not fully scriptable. Only search is permitted. Client SuiteScript is not supported for this record. It is scriptable in server SuiteScript only.
Store Pickup Fulfillment Newly Exposed Available when the Store Pickup feature is enabled. For more information about this record, see Store Pickup.

2017.1 SuiteScript Records Browser

The 2017.1 SuiteScript Records Browser is not yet available.

jQuery UI Library No Longer Loaded on NetSuite Pages

Programmatic access to the NetSuite UI has always required the use of SuiteScript APIs. SuiteScript has never supported direct access to the NetSuite UI through the Document Object Model (DOM). Prior to 2017.1, the jQuery UI library was loaded on each NetSuite page. It is possible that your implementations relied on this library, although this usage was never supported. As of 2017.1, the jQuery UI library is no longer loaded on each NetSuite page. Notice of this change is provided as a courtesy, so you can check your implementations and make changes as needed. If you want to use jQuery UI in your scripts, you must import your own version of this library. For more information about using third party libraries in SuiteScript 2.0, see SuiteScript 2.0 Custom Modules.