SuiteScript 2.x Bundle Installation Script Reference
A bundle installation script's functions are executed automatically during bundle installation, update, or uninstallation, based on one or more of the following triggers:
-
Before Install - Executed before a bundle is installed for the first time in a target account.
-
After Install - Executed after a bundle is installed for the first time in a target account.
-
Before Update - Executed before a bundle in a target account is updated.
-
After Update - Executed after a bundle in a target account is updated.
-
Before Uninstall - Executed before a bundle is uninstalled from a target account.
A bundle installation script file should include a function for at least one of these triggers. If you are using more than one of these, they should all be in the same script file.
The following are example uses for bundle installation script triggered functions:
-
Before Install: Check the existing configuration and setup in the target account prior to bundle installation, and halt the installation with an error message if the target account does not meet minimum requirements to run the solution.
-
After Install: Automate the setup and configuration of the bundled application after it has been installed in the target account, eliminating manual tasks.
-
After Install or After Update: Connect to an external system to fetch some data and complete the setup of the bundled application.
-
Before Update: Manage required data changes in the target account prior to executing an upgrade.
-
Before Uninstall: Reset configuration settings or remove data associated with the bundle being uninstalled.
Two specialized parameters are available to functions in bundle installation scripts, to return the version of bundles, as specified on the Bundle Basics page of the Bundle Builder.
-
The toversion parameter returns the version of the bundle that will be installed in the target account. This parameter is available to Before Install, After Install, Before Update, and After Update functions.
-
The fromversion parameter returns the version of the bundle that is currently installed in the target account. This parameter is available to Before Update and After Update functions.
A bundle installation script file can include calls to functions in other script files, if those files are added as library script files on the script record. Any .js files for library script files are automatically included in the bundle when it is added to target accounts.
Bundle installation scripts can call scheduled scripts, but only in the After Install and After Update functions. Calls to scheduled scripts are not supported in the Before Install, Before Update, and Before Uninstall functions.
Bundle installation scripts are governed by a maximum of 10,000 units per execution.
You can create multiple deployments for each bundle installation script, with different parameters for each, but only one deployment can be associated with each bundle. When you associate a bundle installation script with a bundle, you select a specific script deployment.
Bundle installation scripts need to be executed with administrator privileges, so the Execute as Role field should always be set to Administrator on the script deployment record.
Bundle installation scripts can only be run in target accounts if the Status is set to Released. The Status should be set to Testing if you want to debug the script.
Any bundle installation script failure terminates bundle installation, update, or uninstallation.
Bundle installation scripts can include their own error handling, in addition to errors thrown by SuiteBundler and SuiteScript. An error thrown by a bundle installation script returns an error code of “Installation Error”, followed by the text defined by the script author.