2/28/2014 Scheduling APIs

SuiteCloud (Customization, Scripting, and Web Services) : SuiteScript : SuiteScript API : SuiteScript Functions : Scheduling APIs

Scheduling APIs

The scheduling APIs are used to start, gather information about, and pause, scripts until a more
appropriate time.
nlapiScheduleScript(scriptId, deployId, params)
nlapiSetRecoveryPoint()
nlapiYieldScript()
For a complete overview of working with scheduled scripts in NetSuite, see Scheduled
Scripts.

nlapiScheduleScript(scriptId, deployId, params)

A call to this API places a scheduled script into the NetSuite scheduling queue. For this to work,
the scheduled script must have a status of Not Scheduled on the Script Deployment page. If
the script's status is set to Testing on the Script Deployment page, the API will not place the
script into the scheduling queue.
If the deployment status on the Script Deployment page is set to Scheduled, the script will be
placed into the queue according to the time(s) specified on the Script Deployment page.
The nlapiScheduleScript API consumes 20 units per call. This API is supported in user event,
portlet, scheduled, and Suitelet scripts.

Important: There is no unit metering if you are re-queueing the current script (see Example 1 -
Rescheduling a Script). Note, however, nlapiScheduleScript is still 20 units per call if
you are trying to schedule other scripts.

One or more calls to nlapiScheduleScript can be made from Suitelet, user event, and portlet
scripts. Note that you can also call nlapiScheduleScript from within a scheduled script to:
1. Place the currently executing scheduled script back into the scheduled script workqueue.
2. Call another scheduled script. When the new script is called, it is then put in the scheduled script
workqueue.
3. Place a scheduled script into the queue from another script type, such as a user event script or a
Suitelet.

Note: Only administrators can run scheduled scripts. If a user event script calls
nlapiScheduleScript, the user event script has to be deployed with admin permissions.

For additional details specific to using nlapiScheduleScript, see Using nlapiScheduleScript to Deploy a
Script into the Scheduling Queue.
For general details on working with scheduled scripts, see Overview of Scheduled Script Topics.

Parameters
scriptId {string | int} [required] - The script internalId or custom scriptId
deployId {string | int} [optional] - The deployment internal ID or script ID. If empty, the first
“free” deployment will be used. Free means that the script's deployment status appears
as Not Scheduled or Completed. If there are multiple “free” scripts, the NetSuite scheduler
will take the first free script that appears in the scheduling queue.

Important: deployId is a required argument if you are calling nlapiScheduleScript to requeue a

scheduled script that is currently executing. This argument is also required if, from
within a scheduled script, you are calling nlapiScheduleScript to queue another
scheduled script that may be multiple deployments (and therefore multiple deployment
IDs). In this case you must specify which of the script's deployments you want to
schedule.

params {Object} [optional] - Object of name/values used in this schedule script instance -
used to override the script parameters values for this execution.
Note that name values are the script parameter internal IDs. If you are not familiar with
https://system.na1.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteScript/SchedulingAPIs.html#bridg… 1/6
2/28/2014 Scheduling APIs
what a script parameter is in the context of SuiteScript, see Creating Script Parameters
Overview in the NetSuite Help Center.

Returns
A string whose value is QUEUED if the script was successfully queued by this call, or it
returns the script's current status. Valid status values are:
INQUEUE - The script you requested is already in a queue and waiting to be run. This
script cannot be requested again until it finishes processing. If the script is INQUEUE,
you must try again later if you want to run the script.
INPROGRESS - The scheduled script is currently running.
SCHEDULED - The script's deployment status is set to scheduled and will be picked
up and put into the execution queue.

Important: This API returns NULL if the scheduled script is undeployed or invalid.

Example 1 - Rescheduling a Script

Use nlapiScheduleScript, nlobjContext.getScriptId() and nlobjContext.getDeploymentId() to
reschedule the currently executing scheduled script if there are more sales orders to update
when the unit usage limit is reached.

Important: There is no unit metering if you are re-queueing the current script. In the following
sample, for example, nlapiScheduleScript consumes no units. Note, however, that
nlapiScheduleScript is still 20 units per call if you are trying to schedule other scripts.

function updateSalesOrders()
{
var context = nlapiGetContext();
var searchresults = nlapiSearchRecord('salesorder',
'customscript_orders_to_update')
if ( searchresults == null )
return;
for ( var i = 0; i < searchresults.length; i++ )
{
nlapiSubmitField('salesorder', searchresults[i].getId(), 'custbody_approved',
'T')
if ( context.getRemainingUsage() <= 0 && (i+1) < searchresults.length )
{
var status = nlapiScheduleScript(context.getScriptId(),
context.getDeploymentId())
if ( status == 'QUEUED' )
break;
}
}
}

Example 2
See more examples in the section Scheduled Script Samples.
Back to Scheduling APIs | Back to SuiteScript Functions

nlapiSetRecoveryPoint()
Creates a recovery point saving the state of the script's execution. When NetSuite resumes the
execution of the script, it resumes the script at the specified recovery point. Also note that
when the script is resumed, its governance units are reset. Be aware, however, all scheduled
scripts have a 50 MB memory limit. For complete details on scheduled script memory limits, see
Understanding Memory Usage in Scheduled Scripts.
A typical implementation for this API might be as follows. Based on the status returned by
nlapiSetRecoveryPoint(), the script executes different logic.

res = nlapiSetRecoveryPoint()
if (res.status == ‘FAILURE')
examine the reason and either cleanup/try again OR exit
else if (res.status == ‘SUCCESS')
do X
else if (res.status == ‘RESUME')
examine the reason and react appropriately
https://system.na1.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteScript/SchedulingAPIs.html#bridg… 2/6
2/28/2014 Scheduling APIs
do Z
do A

Note you can use nlapiSetRecoveryPoint() in conjunction with nlapiYieldScript() to effectively

pause the script until a later time when it is more appropriate to run the script.

Important: This API can only be called from scheduled scripts; calling this API from any other
script type will result in an error.

The nlapiSetRecoveryPoint() API consumes 100 units per call.

For an overview of possible use cases for setting recovery points in your scheduled scripts, see
Setting Recovery Points in Scheduled Scripts.

Returns
Native Javascript Object
status {string}
SUCCESS – Save point was created.
FAILURE – The recovery point was unable to be created. Returns the reason for
the failure and the footprint size of the script.
RESUME – Script is being resumed.
reason {string}
SS_NLAPIYIELDSCRIPT - Yield was called.
SS_ABORT -The JVM unintentionally stopped (native error, no response, etc.) --
mimics normal "ABORT" states.
SS_MAJOR_RELEASE – A major NetSuite release is pending, processes are being
stopped.
SS_EXCESSIVE_MEMORY_FOOTPRINT – The saved object is too big.
SS_CANCELLED – A user requested that the script stop.
SS_DISALLOWED_OBJECT_REFERENCE – The script is attempting to serialize an
object that is not serializable (see Supported Objects).
size {integer} – The size of the saved object.
information {string} – Additional information about the status.

Important: If an nlapiYieldScript() or nlapiSetRecoveryPoint() returns a FAILURE with

SS_DISALLOWED_OBJEC T_REFERENC E, the object type will be stored in the
information property. To fix this problem, find the offending reference and set it to null.

Supported Objects:
All JavaScript native types, plus:
nlobjConfiguration
nlobjContext
nlobjError
nlobjFile
nlobjRecord
nlobjSubrecord
nlobjSearchColumn
nlobjSearchFilter
nlobjSearchResult
nlobjSearchResultCell
all 3rd party XML Library objects

Important: All other object types are not supported.

Example – Setting a recovery point, handling errors, and resuming a script

The following sample shows a scheduled script that runs a customer search. The script iterates
through the results of the customer search, and after every five records, sets a recovery point.
If there is an unexpected server failure, the script will resume from the current "i" index of the
search results.

The handleC ustomer(...) function in this script is not defined. The function is there only to
https://system.na1.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteScript/SchedulingAPIs.html#bridg… 3/6
2/28/2014 Scheduling APIs
demonstrate generic processing you could do with search results.
Note:
This script also checks the governance of the script. If the script goes above the governance
threshold, the script is yielded. Based on the status returned by setRecoveryPoint(), an
execution log is created to document the reason this scrip was resumed. And based on the
reason, a more descriptive text message is thrown to the user. Note that if the reason is
SS_EXCESSIVE_MEMORY_FOOTPRINT the cleanUpMemory() function is executed and an
additional recovery point is set.

function runScheduledScript(status, queueid)

{
var records = nlapiSearchRecord('customer', 15);
for( var i = 0; i < records.length; i++ )
{
handleCustomer(records[i].getRecordType(), records[i].getId());

if( (i % 5) == 0 ) setRecoveryPoint(); //every 5 customers, we want to set a

recovery point so that, in case of an unexpected server failure, we resume from the
current "i" index instead of 0
checkGovernance();
}
}
function setRecoveryPoint()
{
var state = nlapiSetRecoveryPoint(); //100 point governance
if( state.status == 'SUCCESS' ) return; //we successfully create a new recovery
point
if( state.status == 'RESUME' ) //a recovery point was previously set, we are resuming
due to some unforeseen error
{
nlapiLogExecution("ERROR", "Resuming script because of " + state.reason+". Size =
"+ state.size);
handleScriptRecovery();
}
else if ( state.status == 'FAILURE' ) //we failed to create a new recovery point
{
nlapiLogExecution("ERROR","Failed to create recovery point. Reason =
"+state.reason + " / Size = "+ state.size);
handleRecoveryFailure(state);
}
}
function checkGovernance()
{
var context = nlapiGetContext();
if( context.getRemainingUsage() < myGovernanceThreshold )
{
var state = nlapiYieldScript();
if( state.status == 'FAILURE'
{
nlapiLogExecution("ERROR","Failed to yield script, exiting: Reason =
"+state.reason + " / Size = "+ state.size);
throw "Failed to yield script";
}
else if ( state.status == 'RESUME' )
{
nlapiLogExecution("AUDIT", "Resuming script because of " + state.reason+". Size =
"+ state.size);
}
// state.status will never be SUCCESS because a success would imply a yield has
occurred. The equivalent response would be yield
}
}

function handleRecoverFailure(failure)
{
if( failure.reason == 'SS_MAJOR_RELEASE" ) throw "Major Update of NetSuite in
progress, shutting down all processes";
if( failure.reason == 'SS_CANCELLED' ) throw "Script Cancelled due to UI
interaction";
if( failure.reason == 'SS_EXCESSIVE_MEMORY_FOOTPRINT ) { cleanUpMemory();
setRecoveryPoint(); }//avoid infinite loop
if( failure.reason == 'SS_DISALLOWED_OBJECT_REFERENCE' ) throw "Could not set
recovery point because of a reference to a non-recoverable object: "+
failure.information;
}
https://system.na1.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteScript/SchedulingAPIs.html#bridg… 4/6
2/28/2014 Scheduling APIs

function cleanUpMemory(){...set references to null, dump values seen in maps, etc}

Back to Scheduling APIs | Back to SuiteScript Functions

nlapiYieldScript()
Creates a recovery point and then reschedules the script. The newly rescheduled script has its
governance units reset, and is then placed at the back of the scheduled script queue. To
summarize, nlapiYieldScript works as follows:
1. Creates a new recovery point.
2. Creates a new scheduled script with a governance reset.
3. Associates the recovery point to the scheduled script
4. Puts the script at the back of the scheduled script queue.

Note: If the yield call fails, a FAILURE status will be returned. On success, the call does not return
until the script is resumed.

Calling this function consumes no governance units. Note also, calling this API resets the unit
counter for the currently executing script. Be aware, however, all scheduled scripts have a 50
MB memory limit. Calling this API will not reset the memory size of the script to 0. It only resets
the governance units. For complete details on scheduled script memory limits, see
Understanding Memory Usage in Scheduled Scripts.

Note: This API can only be called from scheduled scripts. C alling this API from any other script type
will result in an error.

Returns
Native Javascript Object
status {string}
FAILURE – The recovery point was unable to be created. Returns the reason for
the failure and the footprint size of the script.
RESUME – Script is being resumed.
reason {string}
SS_NLAPIYIELDSCRIPT - Yield was called.
SS_ABORT -The JVM unintentionally stopped (native error, no response, etc.) --
mimics normal "ABORT" states.
SS_MAJOR_RELEASE – A major NetSuite release is pending, processes are being
stopped.
SS_EXCESSIVE_MEMORY_FOOTPRINT – The saved object is too big.
SS_CANCELLED – A user requested that the script stop.
SS_DISALLOWED_OBJECT_REFERENCE – The script is attempting to serialize an
object that is not serializable (see Supported Objects).
size {integer} – The size of the saved object.
information {string} – Additional information about the status.
Be careful if using this API within try / catch / finally. On a successful yield, all the finally
blocks will be called, but catches will be ignored.
It is advisable to use the finally block for code which is not going to affect program flow, for
example - writing log entries.
If you have a yield in the try block, it is possible that some instructions in the finally block
will execute before the yield takes place. The same instructions will execute again on
resume.

Supported Objects:
All JavaScript native types, plus:
nlobjConfiguration
nlobjContext
nlobjError
nlobjFile

https://system.na1.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteScript/SchedulingAPIs.html#bridg… 5/6
2/28/2014 Scheduling APIs
nlobjRecord
nlobjSubrecord
nlobjSearchColumn
nlobjSearchFilter
nlobjSearchResult
nlobjSearchResultCell
all 3rd party XML Library objects

Important: All other object types are not supported.

Back to Scheduling APIs | Back to SuiteScript Functions

https://system.na1.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteScript/SchedulingAPIs.html#bridg… 6/6