1. SuiteCloud Platform
  2. SuiteCloud Development Framework
  3. Developing SuiteCloud Projects for SuiteCloud Development Framework
  4. SuiteCloud Project Deployment Preparation
  5. Customizing SuiteApp Project Deployment using SDF Installation Scripts

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:

Note:

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.

Note:

Installation scripts are executed as the role you used to deploy the SuiteApp project.

  1. From your SuiteApp project, open the deploy.xml.

  2. Insert the run element where you want the script to be triggered.

  3. Add a script element inside the run element.

  4. 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>

  5. (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:

  1. The script file is uploaded.

  2. The script record and deployment is created from the XML definition.

  3. 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)

Related Topics

General Notices