Customizing SuiteApp Project Deployment using SDF Installation Scripts
You can incorporate SuiteCloud Development Framework (SDF) installation scripts into your SuiteApp project deployment. An SDF installation script is a type of SuiteScript that can be triggered and run on the target account during SuiteCloud project deployment. This provides capability to perform customization, set up the account, migrate data, and run other tasks during installation of the SuiteApp. For more information, see SuiteScript 2.x SDF Installation Script Type and SDF Installation Scripts as XML Definitions.
To use this feature, you must specify the SDF installation script deployment and when you want it to run from the deploy file of your SuiteApp project. You must include the references you need using script and run elements in the deploy file. SDF deploys referenced components to the target NetSuite account sequentially, first to last in the order they appear.
Depending on the placement of the run element, you can emulate the following script endpoints that were originally included in bundle installation scripts:
-
before install
-
after install
-
before update
-
after update
SDF installation scripts cannot be run before uninstall of an SDF SuiteApp.
The following sections provide more information about customizing SuiteApp project deployment using SDF installation scripts:
Defining When an SDF Installation Script is Run
You can perform this task in a SuiteApp project that contains a SDF installation script file and an sdfinstallationscript
object. The deployment log includes a run scripts line if a valid <run> tag is specified in the deploy.xml. See Handling Exceptions and Monitoring SDF Installation Scripts.
For information about the sdfinstallationscript
object, see SDF Installation Scripts as XML Definitions.
For an example, see Syntax for Triggering an SDF Installation Script Example.
Installation scripts are executed as the role you used to deploy the SuiteApp project.
-
From your SuiteApp project, open the deploy.xml.
-
Insert the run element where you want the script to be triggered.
-
Add a script element inside the run element.
-
Within the script element, reference the XML file path for the
sdfinstallationscript
object and deployment record script ID for the script that you want to execute.<deploy> <run> <script> <path>~/Objects/YOURSCRIPTRECORD.xml</path> <deployment>your_deployment_script_id</deployment> </script> </run> </deploy>
-
(Optional) To run multiple SDF installation scripts, you can individually add more script references inside the same run element, or in a separate run element. See Triggering Multiple SDF Installation Scripts during SuiteApp Project Deployment Example.
Note:You cannot use a wildcard (*) in the path to run multiple installation scripts in a folder.
Syntax for Triggering an SDF Installation Script Example
The following deploy.xml sample contains a run element that uses the file path and script ID of the deployment record to reference the XML definition of the SDF installation script (customscript_install_script.xml) and its deployment record (customdeploy1).
<deploy>
<run>
<script>
<path>~/Objects/customscript_install_script.xml</path>
<deployment>customdeploy1</deployment>
</script>
</run>
</deploy>
Triggering Multiple SDF Installation Scripts during SuiteApp Project Deployment Example
In the following example, multiple SDF installation scripts are triggered at different points during deployment through placement of the run tags.
The following actions will occur for each of the three referenced scripts when they are executed:
-
The script file is uploaded.
-
The script record and deployment is created from the XML definition.
-
The script is executed.
<deploy>
<files>
<path>~/FileCabinet/SuiteApps/com.example.scriptdemo/*</path>
</files>
<run>
<script>
<path>~/Objects/customscript_execute.xml</path>
<deployment>customdeploy_before_objects</deployment>
</script>
</run>
<objects>
<path>~/Objects/*</path>
</objects>
<run>
<script>
<path>~Objects/customscript_execute2.xml</path>
<deployment>customdeploy_1</deployment>
</script>
<script>
<path>~/Objects/customscript_execute.xml</path>
<deployment>customdeploy_after_objects</deployment>
</script>
</run>
</deploy>
Handling Exceptions and Monitoring SDF Installation Scripts
To monitor the progress of your installation scripts and the deployment process of your SuiteApp project, you can do the following:
-
From SuiteCloud IDE, view the deployment log. The deployment log includes a run scripts line if a valid run element is specified in the deploy.xml. For more information about deployment logs, see Deployment Logs for SuiteCloud Projects.
-
In the target NetSuite account, script execution details are logged on the Execution Log tab that appears on the Script page and Script Deployment page. For more information, see SuiteScript Monitoring, Auditing, and Logging.
SDF installation script failures terminate SuiteApp deployments and can include their own error handling in addition to errors thrown by SDF and SuiteScript. An error thrown by an SDF installation script returns an error followed by the text defined by the script author.
The following deployment logs are sample outputs when a valid run element referencing an SDF installation script is included in the deploy file:
Deployment that Successfully Runs an SDF Installation Script
The following text output is representative of a successful SuiteApp project deployment that runs an SDF installation script:
2018-08-07 09:37:04 (PST) Installation started
Info -- Account [(PRODUCTION) DB93_Regress_OW_1326288]
Info -- Publisher ID [com.netsuite]
Info -- SuiteApp [com.netsuite.example(1.0.0)]
Info -- Framework Version [1.0]
Validate manifest -- Success
Validate deploy file -- Success
Validate script file -- Success
Validate objects -- Success
Validate files -- Success
Validate folders -- Success
Validate preferences -- Success
Validate flags -- Success
Validate account settings -- Success
Validate Custom Objects against the Account -- Success
Info -- Current installed version [1.0.0]
Begin deployment -- com.netsuite.example(1.0.0)
Run installation script -- customscript_execute (sdfinstallationscript)
2028-08-07 09:47:18 (PST) Installation COMPLETE (0 minutes 55 seconds)
Deployment Containing a User-defined Script Exception
In an SDF installation script, you can write custom code to throw a friendlier error to users that install the SuiteApp and to keep in the SuiteApp project deployment log.
...
Validate account settings -- Success
Validate Custom Objects against the Account -- Success
Info -- Current installed version [1.0.0]
Begin deployment -- com.netsuite.example(1.0.0)
Run installation script -- customscript_execute (sdfinstallationscript)
*** ERROR ***
An installation script execution error occurred.
Details: I am a user-defined thrown exception.
File: ~/FileCabinet/SuiteApps/com.netsuite.example/execute.js
2028-08-07 09:38:05 (PST) Installation FAILED (1 minute 2 seconds)
Deployment with JavaScript Exception
The following log captures a JavaScript error pointing to a problem in the SDF installation script, in this case a type error.
...
Validate account settings -- Success
Validate Custom Objects against the Account -- Success
Info -- Current installed version [1.0.0]
Begin deployment -- com.netsuite.example(1.0.0)
Run installation script -- customscript_execute (sdfinstallationscript)
*** ERROR ***
An installation script execution error occurred.
Details: org.mozilla.javascript.EcmaError: TypeError: Cannot find function isFeatsureInEffect in object runtime. (/SuiteApps/com.netsuite.example/execute.js#7)
File: ~/FileCabinet/SuiteApps/com.netsuite.example/execute.js
2028-08-07 09:38:05 (PST) Installation FAILED (1 minute 2 seconds)
Deployment with SuiteScript Error (JSON format)
The following log displays a sample SuiteScript error log in JSON format. The deployment was stopped when a problem occurred during execution of the SDF installation script. The error is generated by SuiteScript as a full stacktrace in JSON format.
In an SDF installation script, you can include a try/catch block with logic to throw your own user-facing error message in place of the SuiteScript error.
....
Validate account settings -- Success
Validate Custom Objects against the Account -- Success
Info -- Current installed version [1.0.0]
Begin deployment -- com.netsuite.example(1.0.0)
Run installation script -- customscript_execute (sdfinstallationscript)
*** ERROR ***
An installation script execution error occurred.
Details: {"type":"error.SuiteScriptError","name":"INSUFFICIENT_PERMISSION","message":"Permission Violation: You need the 'Transactions -> Sales Order' permission to access this page. Please contact your account administrator.","stack":["createError(N/error.js:469)"," <anonymous>(SYSTEM_LIBS:3704)"," <anonymous>(SYSTEM_LIBS:2702)"," <anonymous>(SYSTEM_LIBS:2819)","invokeOn(SYSTEM_LIBS:3703)","createRecord_impl(N/record/recordImpl.js:24)","createRecord(N/record/recordImpl.js:16)","createRecord(N/record.js:15)","run(/SuiteApps/com.netsuite.example/execute.js:16)","<anonymous>(INVOCATION_WRAPPER:1)"],"notifyOff":false},"id":"","notifyOff":false,"userFacing":false}
File: ~/FileCabinet/SuiteApps/com.netsuite.example/execute.js
2028-08-07 09:38:05 (PST) Installation FAILED (1 minute 2 seconds)